chore: sync .mokogitea/workflows/auto-release.yml from moko-platform [skip ci]

chore: cascade main → dev [skip ci]

.mokogitea/workflows/cascade-dev.yml

@@ -1,213 +0,0 @@
-# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
-#
-# SPDX-License-Identifier: GPL-3.0-or-later
-#
-# FILE INFORMATION
-# DEFGROUP: Gitea.Workflow
-# INGROUP: moko-platform.Maintenance
-# REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/moko-platform
-# PATH: /templates/workflows/cascade-dev.yml.template
-# VERSION: 02.00.00
-# BRIEF: Forward-merge main → all open branches after every push to main
-#
-# +========================================================================+
-# |                CASCADE MAIN → ALL BRANCHES                             |
-# +========================================================================+
-# |                                                                        |
-# |  Triggers on every push to main (PR merges, bot commits, etc.)         |
-# |                                                                        |
-# |  1. List all branches matching: dev, rc/*, beta/*, alpha/*             |
-# |  2. For each: create PR (main → branch), auto-merge if clean           |
-# |  3. On conflict: leave PR open for manual resolution                   |
-# |                                                                        |
-# +========================================================================+
-
-name: "Universal: Cascade Main → Dev"
-
-on:
-  push:
-    branches:
-      - main
-  workflow_dispatch:
-
-env:
-  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
-  GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
-  GITEA_ORG: ${{ vars.GITEA_ORG || github.repository_owner }}
-  GITEA_REPO: ${{ vars.GITEA_REPO || github.event.repository.name }}
-
-permissions:
-  contents: write
-  pull-requests: write
-
-jobs:
-  cascade:
-    name: Cascade main → branches
-    runs-on: ubuntu-latest
-    if: >-
-      !contains(github.event.head_commit.message, '[skip ci]') &&
-      !contains(github.event.head_commit.message, '[skip cascade]')
-
-    steps:
-      - name: Discover target branches
-        id: branches
-        env:
-          GA_TOKEN: ${{ secrets.GA_TOKEN }}
-        run: |
-          API="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-
-          # Fetch all branches (paginated)
-          PAGE=1
-          ALL_BRANCHES=""
-          while true; do
-            BATCH=$(curl -sS \
-              -H "Authorization: token ${GA_TOKEN}" \
-              "${API}/branches?page=${PAGE}&limit=50" \
-              | jq -r '.[].name // empty')
-            [ -z "$BATCH" ] && break
-            ALL_BRANCHES="$ALL_BRANCHES $BATCH"
-            PAGE=$((PAGE + 1))
-          done
-
-          # Filter to cascade targets: dev, dev/*, rc/*, beta/*, alpha/*
-          TARGETS=""
-          for BRANCH in $ALL_BRANCHES; do
-            case "$BRANCH" in
-              dev|dev/*|rc/*|beta/*|alpha/*)
-                TARGETS="$TARGETS $BRANCH"
-                ;;
-            esac
-          done
-
-          TARGETS=$(echo "$TARGETS" | xargs)  # trim whitespace
-
-          if [ -z "$TARGETS" ]; then
-            echo "targets=" >> "$GITHUB_OUTPUT"
-            echo "ℹ️  No cascade target branches found"
-          else
-            echo "targets=$TARGETS" >> "$GITHUB_OUTPUT"
-            COUNT=$(echo "$TARGETS" | wc -w)
-            echo "📋 Found ${COUNT} target branch(es): ${TARGETS}"
-          fi
-
-      - name: Cascade to all target branches
-        if: steps.branches.outputs.targets != ''
-        env:
-          GA_TOKEN: ${{ secrets.GA_TOKEN }}
-        run: |
-          API="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-          SHORT_SHA="${GITHUB_SHA:0:7}"
-          TARGETS="${{ steps.branches.outputs.targets }}"
-
-          SUCCESS=0
-          CONFLICTS=0
-          SKIPPED=0
-          FAILED=0
-
-          for BRANCH in $TARGETS; do
-            echo ""
-            echo "═══ main → ${BRANCH} ═══"
-
-            # Check if branch is already up to date
-            ENCODED_BRANCH=$(echo "$BRANCH" | sed 's|/|%2F|g')
-            RESPONSE=$(curl -sS \
-              -H "Authorization: token ${GA_TOKEN}" \
-              "${API}/compare/${ENCODED_BRANCH}...main")
-
-            AHEAD=$(echo "$RESPONSE" | jq '.total_commits // 0')
-
-            if [ "$AHEAD" -eq 0 ]; then
-              echo "  ✅ Already up to date"
-              SKIPPED=$((SKIPPED + 1))
-              continue
-            fi
-
-            echo "  ℹ️  main is ${AHEAD} commit(s) ahead"
-
-            # Check for existing cascade PR
-            EXISTING=$(curl -sS \
-              -H "Authorization: token ${GA_TOKEN}" \
-              "${API}/pulls?state=open&head=${GITEA_ORG}:main&base=${ENCODED_BRANCH}&limit=1")
-
-            EXISTING_COUNT=$(echo "$EXISTING" | jq 'length')
-            PR_NUMBER=""
-
-            if [ "$EXISTING_COUNT" -gt 0 ]; then
-              PR_NUMBER=$(echo "$EXISTING" | jq -r '.[0].number')
-              echo "  ℹ️  Reusing existing PR #${PR_NUMBER}"
-            else
-              # Create cascade PR
-              PR_RESPONSE=$(curl -sS -w "\n%{http_code}" \
-                -X POST \
-                -H "Authorization: token ${GA_TOKEN}" \
-                -H "Content-Type: application/json" \
-                -d "{
-                  \"title\": \"chore: cascade main → ${BRANCH} (${SHORT_SHA}) [skip ci]\",
-                  \"body\": \"## Automatic cascade\\n\\nForward-merging \`main\` (${SHORT_SHA}) into \`${BRANCH}\`.\\n\\nIf conflicts exist, resolve manually and merge.\\n\\n> Auto-created by **Cascade Main → Dev**.\",
-                  \"head\": \"main\",
-                  \"base\": \"${BRANCH}\"
-                }" \
-                "${API}/pulls")
-
-              HTTP_CODE=$(echo "$PR_RESPONSE" | tail -1)
-              BODY=$(echo "$PR_RESPONSE" | sed '$d')
-              PR_NUMBER=$(echo "$BODY" | jq -r '.number // empty')
-
-              if [ "$HTTP_CODE" != "201" ] || [ -z "$PR_NUMBER" ]; then
-                MSG=$(echo "$BODY" | jq -r '.message // .' 2>/dev/null | head -1)
-                echo "  ❌ Failed to create PR (HTTP ${HTTP_CODE}): ${MSG}"
-                FAILED=$((FAILED + 1))
-                continue
-              fi
-
-              echo "  ✅ Created PR #${PR_NUMBER}"
-            fi
-
-            # Try auto-merge
-            PR_DATA=$(curl -sS \
-              -H "Authorization: token ${GA_TOKEN}" \
-              "${API}/pulls/${PR_NUMBER}")
-
-            MERGEABLE=$(echo "$PR_DATA" | jq -r '.mergeable // false')
-
-            if [ "$MERGEABLE" != "true" ]; then
-              echo "  ⚠️  Conflicts — PR #${PR_NUMBER} left open"
-              CONFLICTS=$((CONFLICTS + 1))
-              continue
-            fi
-
-            MERGE_RESPONSE=$(curl -sS -w "\n%{http_code}" \
-              -X POST \
-              -H "Authorization: token ${GA_TOKEN}" \
-              -H "Content-Type: application/json" \
-              -d "{
-                \"Do\": \"merge\",
-                \"merge_message_field\": \"chore: cascade main → ${BRANCH} [skip ci]\",
-                \"delete_branch_after_merge\": false
-              }" \
-              "${API}/pulls/${PR_NUMBER}/merge")
-
-            MERGE_HTTP=$(echo "$MERGE_RESPONSE" | tail -1)
-
-            if [ "$MERGE_HTTP" = "200" ] || [ "$MERGE_HTTP" = "204" ]; then
-              echo "  ✅ Merged — ${BRANCH} is in sync"
-              SUCCESS=$((SUCCESS + 1))
-            else
-              MERGE_BODY=$(echo "$MERGE_RESPONSE" | sed '$d')
-              echo "  ⚠️  Merge failed (HTTP ${MERGE_HTTP}) — PR #${PR_NUMBER} left open"
-              CONFLICTS=$((CONFLICTS + 1))
-            fi
-          done
-
-          # Summary
-          echo ""
-          echo "════════════════════════════════════════"
-          echo "  ✅ Merged:    ${SUCCESS}"
-          echo "  ⚠️  Conflicts: ${CONFLICTS}"
-          echo "  ⏭️  Up to date: ${SKIPPED}"
-          echo "  ❌ Failed:    ${FAILED}"
-          echo "════════════════════════════════════════"
-
-          if [ "$FAILED" -gt 0 ]; then
-            exit 1
-          fi

.mokogitea/workflows/pr-check.yml

@@ -1,196 +1,508 @@
-# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
-#
+#
-# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-License-Identifier: GPL-3.0-or-later
-#
+#
-# FILE INFORMATION
+# FILE INFORMATION
-# DEFGROUP: Gitea.Workflow
+# DEFGROUP: Gitea.Workflow
-# INGROUP: moko-platform.CI
+# INGROUP: moko-platform.CI
-# REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/moko-platform
+# REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/moko-platform
-# PATH: /templates/workflows/universal/pr-check.yml.template
+# PATH: /templates/workflows/universal/pr-check.yml.template
-# VERSION: 05.00.00
+# VERSION: 09.23.00
-# BRIEF: PR gate — branch policy + code validation before merge
+# BRIEF: PR gate — branch policy + code validation before merge
-
+
-name: "Universal: PR Check"
+name: "Universal: PR Check"
-
+
-on:
+on:
-  pull_request:
+  pull_request:
-    types: [opened, synchronize, reopened, edited]
+    types: [opened, synchronize, reopened, edited]
-
+
-permissions:
+permissions:
-  contents: read
+  contents: read
-  pull-requests: write
+  pull-requests: write
-
+
-env:
+env:
-  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
-
+
-jobs:
+jobs:
-  # ── Branch Policy ──────────────────────────────────────────────────────
+  # ── Branch Policy ──────────────────────────────────────────────────────
-  branch-policy:
+  branch-policy:
-    name: Branch Policy
+    name: Branch Policy
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-latest
-    steps:
+    steps:
-      - name: Check branch merge target
+      - name: Check branch merge target
-        run: |
+        run: |
-          HEAD="${{ github.head_ref }}"
+          HEAD="${{ github.head_ref }}"
-          BASE="${{ github.base_ref }}"
+          BASE="${{ github.base_ref }}"
-
+
-          echo "PR: ${HEAD} → ${BASE}"
+          echo "PR: ${HEAD} → ${BASE}"
-
+
-          ALLOWED=true
+          ALLOWED=true
-          REASON=""
+          REASON=""
-
+
-          case "$HEAD" in
+          case "$HEAD" in
-            feature/*|feat/*)
+            feature/*|feat/*)
-              if [ "$BASE" != "dev" ]; then
+              if [ "$BASE" != "dev" ]; then
-                ALLOWED=false
+                ALLOWED=false
-                REASON="Feature branches must target 'dev', not '${BASE}'"
+                REASON="Feature branches must target 'dev', not '${BASE}'"
-              fi
+              fi
-              ;;
+              ;;
-            fix/*|bugfix/*)
+            fix/*|bugfix/*)
-              if [ "$BASE" != "dev" ]; then
+              if [ "$BASE" != "dev" ]; then
-                ALLOWED=false
+                ALLOWED=false
-                REASON="Fix branches must target 'dev', not '${BASE}'"
+                REASON="Fix branches must target 'dev', not '${BASE}'"
-              fi
+              fi
-              ;;
+              ;;
-            hotfix/*)
+            patch/*)
-              if [ "$BASE" != "dev" ] && [ "$BASE" != "main" ]; then
+              if [ "$BASE" != "dev" ] && [ "$BASE" != "rc" ]; then
-                ALLOWED=false
+                ALLOWED=false
-                REASON="Hotfix branches can only target 'dev' or 'main', not '${BASE}'"
+                REASON="Patch branches must target 'dev' or 'rc', not '${BASE}'"
-              fi
+              fi
-              ;;
+              ;;
-            alpha/*|beta/*)
+            hotfix/*)
-              if [ "$BASE" != "dev" ]; then
+              if [ "$BASE" != "dev" ] && [ "$BASE" != "main" ]; then
-                ALLOWED=false
+                ALLOWED=false
-                REASON="Pre-release branches must target 'dev', not '${BASE}'"
+                REASON="Hotfix branches can only target 'dev' or 'main', not '${BASE}'"
-              fi
+              fi
-              ;;
+              ;;
-            rc/*)
+            rc)
-              if [ "$BASE" != "main" ]; then
+              if [ "$BASE" != "main" ]; then
-                ALLOWED=false
+                ALLOWED=false
-                REASON="Release candidate branches must target 'main', not '${BASE}'"
+                REASON="RC branch can only merge into 'main', not '${BASE}'"
-              fi
+              fi
-              ;;
+              ;;
-            dev)
+            dev)
-              if [ "$BASE" != "main" ]; then
+              if [ "$BASE" != "main" ]; then
-                ALLOWED=false
+                ALLOWED=false
-                REASON="Dev branch can only merge into 'main', not '${BASE}'"
+                REASON="Dev branch can only merge into 'main', not '${BASE}'"
-              fi
+              fi
-              ;;
+              ;;
-          esac
+          esac
-
+
-          if [ "$ALLOWED" = false ]; then
+          if [ "$ALLOWED" = false ]; then
-            echo "::error::${REASON}"
+            echo "::error::${REASON}"
-            echo "## Branch Policy Violation" >> $GITHUB_STEP_SUMMARY
+            echo "## Branch Policy Violation" >> $GITHUB_STEP_SUMMARY
-            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
-            echo "${REASON}" >> $GITHUB_STEP_SUMMARY
+            echo "${REASON}" >> $GITHUB_STEP_SUMMARY
-            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
-            echo "### Allowed merge paths:" >> $GITHUB_STEP_SUMMARY
+            echo "### Allowed merge paths:" >> $GITHUB_STEP_SUMMARY
-            echo "- \`feature/*\` → \`dev\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`feature/*\` → \`dev\`" >> $GITHUB_STEP_SUMMARY
-            echo "- \`fix/*\` → \`dev\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`fix/*\` → \`dev\`" >> $GITHUB_STEP_SUMMARY
-            echo "- \`hotfix/*\` → \`dev\` or \`main\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`hotfix/*\` → \`dev\` or \`main\`" >> $GITHUB_STEP_SUMMARY
-            echo "- \`dev\` → \`main\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`dev\` → \`main\`" >> $GITHUB_STEP_SUMMARY
-            echo "- \`rc/*\` → \`main\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`rc/*\` → \`main\`" >> $GITHUB_STEP_SUMMARY
-            exit 1
+            exit 1
-          fi
+          fi
-
+
-          echo "Branch policy: OK (${HEAD} → ${BASE})"
+          echo "Branch policy: OK (${HEAD} → ${BASE})"
-          echo "## Branch Policy: Passed" >> $GITHUB_STEP_SUMMARY
+          echo "## Branch Policy: Passed" >> $GITHUB_STEP_SUMMARY
-
+
-  # ── Code Validation ────────────────────────────────────────────────────
+  # ── Code Validation ────────────────────────────────────────────────────
-  validate:
+  validate:
-    name: Validate PR
+    name: Validate PR
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-latest
-
+
-    steps:
+    steps:
-      - name: Checkout
+      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v4
-
+
-      - name: Detect platform
+      - name: Check for merge conflict markers
-        id: platform
+        run: |
-        run: |
+          CONFLICTS=$(grep -rn '<<<<<<< \|>>>>>>> \|^=======$' --include='*.php' --include='*.xml' --include='*.css' --include='*.js' --include='*.json' --include='*.md' --include='*.yml' --include='*.yaml' --include='*.ini' --include='*.txt' . 2>/dev/null | grep -v '.git/' || true)
-          # Read platform from XML manifest (<platform> tag) or plain text fallback
+          if [ -n "$CONFLICTS" ]; then
-          PLATFORM=$(sed -n 's/.*<platform>\([^<]*\)<\/platform>.*/\1/p' .mokogitea/manifest.xml 2>/dev/null | head -1)
+            echo "::error::Merge conflict markers found in source files"
-          [ -z "$PLATFORM" ] && PLATFORM=$(cat .mokogitea/manifest.xml 2>/dev/null | tr -d '[:space:]')
+            echo "## Conflict Markers Found" >> $GITHUB_STEP_SUMMARY
-          [ -z "$PLATFORM" ] && PLATFORM="generic"
+            echo '```' >> $GITHUB_STEP_SUMMARY
-          echo "platform=$PLATFORM" >> "$GITHUB_OUTPUT"
+            echo "$CONFLICTS" >> $GITHUB_STEP_SUMMARY
-
+            echo '```' >> $GITHUB_STEP_SUMMARY
-      - name: Setup PHP
+            exit 1
-        if: steps.platform.outputs.platform == 'joomla' || steps.platform.outputs.platform == 'dolibarr'
+          fi
-        run: |
+          echo "No conflict markers found"
-          if ! command -v php &> /dev/null; then
+
-            sudo apt-get update -qq
+      - name: Detect platform
-            sudo apt-get install -y -qq php-cli php-mbstring php-xml >/dev/null 2>&1
+        id: platform
-          fi
+        run: |
-
+          # Read platform from XML manifest (<platform> tag) or plain text fallback
-      - name: PHP syntax check
+          PLATFORM=$(sed -n 's/.*<platform>\([^<]*\)<\/platform>.*/\1/p' .mokogitea/manifest.xml 2>/dev/null | head -1)
-        if: steps.platform.outputs.platform == 'joomla' || steps.platform.outputs.platform == 'dolibarr'
+          [ -z "$PLATFORM" ] && PLATFORM=$(cat .mokogitea/manifest.xml 2>/dev/null | tr -d '[:space:]')
-        run: |
+          [ -z "$PLATFORM" ] && PLATFORM="generic"
-          ERRORS=0
+          echo "platform=$PLATFORM" >> "$GITHUB_OUTPUT"
-          while IFS= read -r -d '' file; do
+
-            if ! php -l "$file" 2>&1 | grep -q "No syntax errors"; then
+      - name: Setup PHP
-              ERRORS=$((ERRORS + 1))
+        if: steps.platform.outputs.platform == 'joomla' || steps.platform.outputs.platform == 'dolibarr'
-            fi
+        run: |
-          done < <(find . -name "*.php" -not -path "./.git/*" -not -path "./vendor/*" -print0)
+          if ! command -v php &> /dev/null; then
-          echo "PHP lint: ${ERRORS} error(s)"
+            sudo apt-get update -qq
-          [ "$ERRORS" -eq 0 ] || { echo "::error::PHP syntax errors found"; exit 1; }
+            sudo apt-get install -y -qq php-cli php-mbstring php-xml >/dev/null 2>&1
-
+          fi
-      - name: Validate platform manifest
+
-        run: |
+      - name: PHP syntax check
-          PLATFORM="${{ steps.platform.outputs.platform }}"
+        if: steps.platform.outputs.platform == 'joomla' || steps.platform.outputs.platform == 'dolibarr'
-          case "$PLATFORM" in
+        run: |
-            joomla)
+          ERRORS=0
-              MANIFEST=$(find . -maxdepth 3 -name "*.xml" ! -path "./.git/*" -exec grep -l '<extension' {} \; 2>/dev/null | head -1)
+          while IFS= read -r -d '' file; do
-              if [ -z "$MANIFEST" ]; then
+            if ! php -l "$file" 2>&1 | grep -q "No syntax errors"; then
-                echo "::warning::No Joomla manifest found (WaaS site)"
+              ERRORS=$((ERRORS + 1))
-                exit 0
+            fi
-              fi
+          done < <(find . -name "*.php" -not -path "./.git/*" -not -path "./vendor/*" -print0)
-              echo "Manifest: ${MANIFEST}"
+          echo "PHP lint: ${ERRORS} error(s)"
-              if command -v php &> /dev/null; then
+          [ "$ERRORS" -eq 0 ] || { echo "::error::PHP syntax errors found"; exit 1; }
-                php -r "libxml_use_internal_errors(true); \$x = simplexml_load_file('$MANIFEST'); if(!\$x){foreach(libxml_get_errors() as \$e) echo \$e->message; exit(1);}" || { echo "::error::Manifest XML is malformed"; exit 1; }
+
-              fi
+      - name: Joomla JEXEC guard check
-              for ELEMENT in name version description; do
+        if: steps.platform.outputs.platform == 'joomla'
-                grep -q "<${ELEMENT}>" "$MANIFEST" || { echo "::error::Missing <${ELEMENT}> in manifest"; exit 1; }
+        run: |
-              done
+          ERRORS=0
-              echo "Joomla manifest valid"
+          while IFS= read -r -d '' file; do
-              ;;
+            # Skip vendor, node_modules, and index.html stub files
-            dolibarr)
+            case "$file" in ./vendor/*|./node_modules/*) continue ;; esac
-              MOD_FILE=$(find . -maxdepth 4 -name "mod*.class.php" ! -path "./.git/*" -exec grep -l 'extends DolibarrModules' {} \; 2>/dev/null | head -1)
+            # Check first 10 lines for JEXEC or JPATH guard
-              if [ -z "$MOD_FILE" ]; then
+            if ! head -20 "$file" | grep -qE "defined\s*\(\s*['\"](_JEXEC|JPATH_BASE|\\\\JPATH_PLATFORM)['\"]"; then
-                echo "::error::No mod*.class.php found"
+              echo "::error file=${file}::Missing JEXEC guard: ${file}"
-                exit 1
+              ERRORS=$((ERRORS + 1))
-              fi
+            fi
-              echo "Dolibarr module: ${MOD_FILE}"
+          done < <(find . -name "*.php" -path "*/src/*" -not -path "./.git/*" -not -path "./vendor/*" -print0)
-              ;;
+          if [ "$ERRORS" -gt 0 ]; then
-            *)
+            echo "::error::${ERRORS} PHP file(s) missing defined('_JEXEC') or die guard"
-              echo "Generic platform — no manifest validation"
+            echo "## JEXEC Guard Check: Failed" >> $GITHUB_STEP_SUMMARY
-              ;;
+            echo "${ERRORS} file(s) in src/ are missing the Joomla execution guard." >> $GITHUB_STEP_SUMMARY
-          esac
+            exit 1
-
+          fi
-      - name: Check update stream format
+          echo "JEXEC guard: OK"
-        run: |
+
-          PLATFORM="${{ steps.platform.outputs.platform }}"
+      - name: Joomla directory listing protection
-          case "$PLATFORM" in
+        if: steps.platform.outputs.platform == 'joomla'
-            joomla)
+        run: |
-              if [ -f "updates.xml" ]; then
+          MISSING=0
-                if command -v php &> /dev/null; then
+          SOURCE_DIR="src"
-                  php -r "libxml_use_internal_errors(true); \$x = simplexml_load_file('updates.xml'); if(!\$x){foreach(libxml_get_errors() as \$e) echo \$e->message; exit(1);}" || { echo "::error::updates.xml is malformed"; exit 1; }
+          [ ! -d "$SOURCE_DIR" ] && exit 0
-                fi
+          while IFS= read -r dir; do
-                echo "updates.xml valid"
+            if [ ! -f "${dir}/index.html" ]; then
-              fi
+              echo "::warning::Missing index.html in ${dir} (directory listing protection)"
-              ;;
+              MISSING=$((MISSING + 1))
-            dolibarr)
+            fi
-              [ -f "update.txt" ] && echo "update.txt present" || echo "::warning::No update.txt"
+          done < <(find "$SOURCE_DIR" -type d -not -path "./.git/*" -not -path "*/vendor/*" -not -path "*/node_modules/*")
-              ;;
+          if [ "$MISSING" -gt 0 ]; then
-          esac
+            echo "## Directory Protection" >> $GITHUB_STEP_SUMMARY
-
+            echo "${MISSING} director(ies) missing index.html" >> $GITHUB_STEP_SUMMARY
-      - name: Verify package source
+          fi
-        run: |
+          echo "Directory protection: ${MISSING} missing (advisory)"
-          SOURCE_DIR="src"
+
-          [ ! -d "$SOURCE_DIR" ] && SOURCE_DIR="htdocs"
+      - name: Joomla script file and asset checks
-          if [ ! -d "$SOURCE_DIR" ]; then
+        if: steps.platform.outputs.platform == 'joomla'
-            echo "::warning::No src/ or htdocs/ directory"
+        run: |
-            exit 0
+          ERRORS=0
-          fi
+          MANIFEST=$(find . -maxdepth 3 -name "*.xml" ! -path "./.git/*" -exec grep -l '<extension' {} \; 2>/dev/null | head -1)
-          FILE_COUNT=$(find "$SOURCE_DIR" -type f | wc -l)
+          [ -z "$MANIFEST" ] && exit 0
-          echo "Source: ${FILE_COUNT} files"
+          MANIFEST_DIR=$(dirname "$MANIFEST")
-          [ "$FILE_COUNT" -gt 0 ] || { echo "::error::Source directory is empty"; exit 1; }
+
+          # Check scriptfile exists if declared
+          SCRIPTFILE=$(sed -n 's/.*<scriptfile>\([^<]*\)<\/scriptfile>.*/\1/p' "$MANIFEST" 2>/dev/null)
+          if [ -n "$SCRIPTFILE" ]; then
+            if [ ! -f "${MANIFEST_DIR}/${SCRIPTFILE}" ]; then
+              echo "::error::Manifest declares <scriptfile>${SCRIPTFILE}</scriptfile> but file not found at ${MANIFEST_DIR}/${SCRIPTFILE}"
+              ERRORS=$((ERRORS + 1))
+            else
+              echo "Script file: ${MANIFEST_DIR}/${SCRIPTFILE} (OK)"
+            fi
+          fi
+
+          # Require joomla.asset.json and validate it
+          ASSET_JSON=$(find "$MANIFEST_DIR" -name "joomla.asset.json" -not -path "./.git/*" 2>/dev/null | head -1)
+          if [ -z "$ASSET_JSON" ]; then
+            echo "::error::joomla.asset.json not found — Joomla asset system is required"
+            ERRORS=$((ERRORS + 1))
+          else
+            if command -v php &> /dev/null; then
+              php -r "json_decode(file_get_contents('$ASSET_JSON')); if(json_last_error()!==JSON_ERROR_NONE){echo json_last_error_msg();exit(1);}" 2>&1 || {
+                echo "::error::joomla.asset.json is not valid JSON"
+                ERRORS=$((ERRORS + 1))
+              }
+            fi
+            echo "joomla.asset.json: valid"
+          fi
+
+          # Validate all XML files in src/ are well-formed
+          XML_ERRORS=0
+          if command -v php &> /dev/null; then
+            while IFS= read -r -d '' xmlfile; do
+              if ! php -r "libxml_use_internal_errors(true); \$x = simplexml_load_file('$xmlfile'); if(!\$x){foreach(libxml_get_errors() as \$e) echo trim(\$e->message) . ' in $xmlfile'; exit(1);}" 2>&1; then
+                XML_ERRORS=$((XML_ERRORS + 1))
+              fi
+            done < <(find "$MANIFEST_DIR" -name "*.xml" -not -path "./.git/*" -print0)
+          fi
+          if [ "$XML_ERRORS" -gt 0 ]; then
+            echo "::error::${XML_ERRORS} XML file(s) are malformed"
+            ERRORS=$((ERRORS + 1))
+          else
+            echo "XML well-formedness: OK"
+          fi
+
+          [ "$ERRORS" -gt 0 ] && exit 1
+          echo "Joomla asset checks: OK"
+
+      - name: Validate platform manifest
+        run: |
+          PLATFORM="${{ steps.platform.outputs.platform }}"
+          case "$PLATFORM" in
+            joomla)
+              MANIFEST=$(find . -maxdepth 3 -name "*.xml" ! -path "./.git/*" -exec grep -l '<extension' {} \; 2>/dev/null | head -1)
+              if [ -z "$MANIFEST" ]; then
+                echo "::warning::No Joomla manifest found (WaaS site)"
+                exit 0
+              fi
+              echo "Manifest: ${MANIFEST}"
+              if command -v php &> /dev/null; then
+                php -r "libxml_use_internal_errors(true); \$x = simplexml_load_file('$MANIFEST'); if(!\$x){foreach(libxml_get_errors() as \$e) echo \$e->message; exit(1);}" || { echo "::error::Manifest XML is malformed"; exit 1; }
+              fi
+              for ELEMENT in name version description; do
+                grep -q "<${ELEMENT}>" "$MANIFEST" || { echo "::error::Missing <${ELEMENT}> in manifest"; exit 1; }
+              done
+              # Block legacy raw/branch update server URLs on MokoGitea
+              RAW_URLS=$(grep -n 'raw/branch' "$MANIFEST" | grep -i 'mokoconsulting\|mokogitea\|git\.mokoconsulting\.tech' || true)
+              if [ -n "$RAW_URLS" ]; then
+                echo "::error::Manifest contains legacy raw/branch update server URL on MokoGitea. Use the Gitea Pages URL instead (e.g. /{REPO}/updates.xml not /{REPO}/raw/branch/main/updates.xml)"
+                echo "$RAW_URLS"
+                exit 1
+              fi
+              echo "Joomla manifest valid"
+              ;;
+            dolibarr)
+              MOD_FILE=$(find . -maxdepth 4 -name "mod*.class.php" ! -path "./.git/*" -exec grep -l 'extends DolibarrModules' {} \; 2>/dev/null | head -1)
+              if [ -z "$MOD_FILE" ]; then
+                echo "::error::No mod*.class.php found"
+                exit 1
+              fi
+              echo "Dolibarr module: ${MOD_FILE}"
+              ;;
+            *)
+              echo "Generic platform — no manifest validation"
+              ;;
+          esac
+
+      - name: Check update stream format
+        run: |
+          PLATFORM="${{ steps.platform.outputs.platform }}"
+          case "$PLATFORM" in
+            joomla)
+              if [ -f "updates.xml" ]; then
+                if command -v php &> /dev/null; then
+                  php -r "libxml_use_internal_errors(true); \$x = simplexml_load_file('updates.xml'); if(!\$x){foreach(libxml_get_errors() as \$e) echo \$e->message; exit(1);}" || { echo "::error::updates.xml is malformed"; exit 1; }
+                fi
+                echo "updates.xml valid"
+              fi
+              ;;
+            dolibarr)
+              [ -f "update.txt" ] && echo "update.txt present" || echo "::warning::No update.txt"
+              ;;
+          esac
+
+      - name: Validate Joomla language files
+        if: steps.platform.outputs.platform == 'joomla'
+        run: |
+          ERRORS=0
+          WARNINGS=0
+
+          # Require both en-GB and en-US language directories
+          LANG_ROOT=$(find . -path "*/language" -type d -not -path "./.git/*" 2>/dev/null | head -1)
+          if [ -z "$LANG_ROOT" ]; then
+            echo "No language/ directory found — skipping"
+            exit 0
+          fi
+
+          if [ ! -d "$LANG_ROOT/en-GB" ]; then
+            echo "::error::Missing en-GB language directory (${LANG_ROOT}/en-GB)"
+            ERRORS=$((ERRORS + 1))
+          fi
+          if [ ! -d "$LANG_ROOT/en-US" ]; then
+            echo "::error::Missing en-US language directory (${LANG_ROOT}/en-US)"
+            ERRORS=$((ERRORS + 1))
+          fi
+
+          # Check that en-GB and en-US have matching .ini files
+          if [ -d "$LANG_ROOT/en-GB" ] && [ -d "$LANG_ROOT/en-US" ]; then
+            for GB_INI in "$LANG_ROOT/en-GB"/*.ini; do
+              [ ! -f "$GB_INI" ] && continue
+              US_INI="$LANG_ROOT/en-US/$(basename "$GB_INI")"
+              if [ ! -f "$US_INI" ]; then
+                echo "::error::$(basename "$GB_INI") exists in en-GB but missing from en-US"
+                ERRORS=$((ERRORS + 1))
+              fi
+            done
+            for US_INI in "$LANG_ROOT/en-US"/*.ini; do
+              [ ! -f "$US_INI" ] && continue
+              GB_INI="$LANG_ROOT/en-GB/$(basename "$US_INI")"
+              if [ ! -f "$GB_INI" ]; then
+                echo "::error::$(basename "$US_INI") exists in en-US but missing from en-GB"
+                ERRORS=$((ERRORS + 1))
+              fi
+            done
+          fi
+
+          # Find all .ini language files
+          INI_FILES=$(find . -path "*/language/*/*.ini" -not -path "./.git/*" 2>/dev/null)
+          if [ -z "$INI_FILES" ]; then
+            echo "No .ini language files found"
+            [ "$ERRORS" -gt 0 ] && exit 1
+            exit 0
+          fi
+
+          echo "Found $(echo "$INI_FILES" | wc -l) language file(s)"
+
+          for FILE in $INI_FILES; do
+            FNAME=$(basename "$FILE")
+            LINENUM=0
+            SEEN_KEYS=""
+
+            while IFS= read -r line || [ -n "$line" ]; do
+              LINENUM=$((LINENUM + 1))
+
+              # Skip empty lines and comments
+              [ -z "$line" ] && continue
+              echo "$line" | grep -qE '^\s*;' && continue
+              echo "$line" | grep -qE '^\s*$' && continue
+
+              # Must match KEY="VALUE" format
+              if ! echo "$line" | grep -qE '^[A-Z_][A-Z0-9_]*=".*"$'; then
+                echo "::error file=${FILE},line=${LINENUM}::Malformed line: ${line}"
+                ERRORS=$((ERRORS + 1))
+                continue
+              fi
+
+              # Extract key and check for duplicates
+              KEY=$(echo "$line" | sed 's/=.*//')
+              if echo "$SEEN_KEYS" | grep -qx "$KEY"; then
+                echo "::error file=${FILE},line=${LINENUM}::Duplicate key: ${KEY}"
+                ERRORS=$((ERRORS + 1))
+              fi
+              SEEN_KEYS="${SEEN_KEYS}
+          ${KEY}"
+            done < "$FILE"
+
+            echo "  ${FILE}: checked ${LINENUM} lines"
+          done
+
+          # Cross-check en-GB vs en-US key consistency
+          GB_DIR=$(find . -path "*/language/en-GB" -type d -not -path "./.git/*" 2>/dev/null | head -1)
+          US_DIR=$(find . -path "*/language/en-US" -type d -not -path "./.git/*" 2>/dev/null | head -1)
+
+          if [ -n "$GB_DIR" ] && [ -n "$US_DIR" ]; then
+            for GB_FILE in "$GB_DIR"/*.ini; do
+              [ ! -f "$GB_FILE" ] && continue
+              FNAME=$(basename "$GB_FILE")
+              US_FILE="$US_DIR/$FNAME"
+              [ ! -f "$US_FILE" ] && continue
+
+              GB_KEYS=$(grep -oP '^[A-Z_][A-Z0-9_]*(?==)' "$GB_FILE" 2>/dev/null | sort)
+              US_KEYS=$(grep -oP '^[A-Z_][A-Z0-9_]*(?==)' "$US_FILE" 2>/dev/null | sort)
+
+              # Keys in en-GB but not en-US
+              MISSING_US=$(comm -23 <(echo "$GB_KEYS") <(echo "$US_KEYS"))
+              if [ -n "$MISSING_US" ]; then
+                echo "::warning::Keys in en-GB/$FNAME but missing from en-US/$FNAME:"
+                echo "$MISSING_US" | while read -r k; do echo "  - $k"; done
+                WARNINGS=$((WARNINGS + 1))
+              fi
+
+              # Keys in en-US but not en-GB
+              MISSING_GB=$(comm -13 <(echo "$GB_KEYS") <(echo "$US_KEYS"))
+              if [ -n "$MISSING_GB" ]; then
+                echo "::warning::Keys in en-US/$FNAME but missing from en-GB/$FNAME:"
+                echo "$MISSING_GB" | while read -r k; do echo "  - $k"; done
+                WARNINGS=$((WARNINGS + 1))
+              fi
+            done
+          fi
+
+          {
+            echo "### Language File Validation"
+            echo "| Metric | Count |"
+            echo "|---|---|"
+            echo "| Files checked | $(echo "$INI_FILES" | wc -l) |"
+            echo "| Errors | ${ERRORS} |"
+            echo "| Warnings | ${WARNINGS} |"
+          } >> $GITHUB_STEP_SUMMARY
+
+          if [ "$ERRORS" -gt 0 ]; then
+            echo "::error::Language validation failed with ${ERRORS} error(s)"
+            exit 1
+          fi
+          echo "Language files: OK (${WARNINGS} warning(s))"
+
+      - name: Check changelog has unreleased entry
+        run: |
+          if [ ! -f "CHANGELOG.md" ]; then
+            echo "::warning::No CHANGELOG.md found"
+            exit 0
+          fi
+          # Check for content under [Unreleased] section
+          if ! grep -q "## \[Unreleased\]" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md missing [Unreleased] section"
+            exit 1
+          fi
+          # Check there's at least one entry (Added/Changed/Fixed/Removed) under Unreleased
+          UNRELEASED_CONTENT=$(sed -n '/## \[Unreleased\]/,/## \[/p' CHANGELOG.md | grep -cE '^\s*-\s' || true)
+          if [ "$UNRELEASED_CONTENT" -eq 0 ]; then
+            echo "::error::CHANGELOG.md [Unreleased] section has no entries. Add a changelog entry describing your changes."
+            echo "## Changelog Check: Failed" >> $GITHUB_STEP_SUMMARY
+            echo "The \`[Unreleased]\` section in CHANGELOG.md has no entries." >> $GITHUB_STEP_SUMMARY
+            echo "Add a line like \`- Description of your change\` under a heading (\`### Added\`, \`### Changed\`, \`### Fixed\`, etc.)" >> $GITHUB_STEP_SUMMARY
+            exit 1
+          fi
+          echo "Changelog: ${UNRELEASED_CONTENT} entry/entries in [Unreleased]"
+
+      - name: Verify package source
+        run: |
+          SOURCE_DIR="src"
+          [ ! -d "$SOURCE_DIR" ] && SOURCE_DIR="htdocs"
+          if [ ! -d "$SOURCE_DIR" ]; then
+            echo "::warning::No src/ or htdocs/ directory"
+            exit 0
+          fi
+          FILE_COUNT=$(find "$SOURCE_DIR" -type f | wc -l)
+          echo "Source: ${FILE_COUNT} files"
+          [ "$FILE_COUNT" -gt 0 ] || { echo "::error::Source directory is empty"; exit 1; }
+
+  # ── Pre-Release RC Build ─────────────────────────────────────────────────
+  pre-release:
+    name: Build RC Package
+    runs-on: ubuntu-latest
+    needs: [branch-policy, validate]
+
+    steps:
+      - name: Trigger RC pre-release
+        env:
+          GA_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
+          REPO: ${{ github.repository }}
+          BRANCH: ${{ github.head_ref }}
+          GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
+        run: |
+          curl -s -X POST             "${GITEA_URL}/api/v1/repos/${REPO}/actions/workflows/pre-release.yml/dispatches"             -H "Authorization: token ${GITEA_TOKEN}"             -H "Content-Type: application/json"             -d "{\"ref\":\"${BRANCH}\",\"inputs\":{\"stability\":\"release-candidate\"}}"
+          echo "### Pre-Release" >> $GITHUB_STEP_SUMMARY
+          echo "Triggered RC build on branch \`${BRANCH}\`" >> $GITHUB_STEP_SUMMARY
+
+  # ── Issue Reporter ──────────────────────────────────────────────────────
+  report-issues:
+    name: Report Issues
+    runs-on: ubuntu-latest
+    needs: [branch-policy, validate]
+    if: >-
+      always() &&
+      needs.validate.result == 'failure'
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: automation/ci-issue-reporter.sh
+          sparse-checkout-cone-mode: false
+
+      - name: "File issue for PR validation failure"
+        env:
+          GITEA_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
+          GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
+        run: |
+          chmod +x automation/ci-issue-reporter.sh
+          ./automation/ci-issue-reporter.sh \
+            --gate "PR Validation" \
+            --workflow "PR Check" \
+            --severity error \
+            --details "PR validation failed (syntax, manifest, changelog, or source checks). See the CI run for the specific check that failed."

.mokogitea/workflows/pre-release.yml

@@ -1,246 +1,243 @@
-# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
-#
+#
-# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-License-Identifier: GPL-3.0-or-later
-#
+#
-# FILE INFORMATION
+# FILE INFORMATION
-# DEFGROUP: Gitea.Workflow
+# DEFGROUP: Gitea.Workflow
-# INGROUP: moko-platform.Release
+# INGROUP: moko-platform.Release
-# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
-# PATH: /templates/workflows/universal/pre-release.yml.template
+# PATH: /templates/workflows/universal/pre-release.yml.template
-# VERSION: 05.00.00
+# VERSION: 05.01.00
-# BRIEF: Manual pre-release — builds dev/alpha/beta/rc packages from any branch
+# BRIEF: Manual pre-release -- builds dev/alpha/beta/rc packages from any branch
-
+
-name: "Universal: Pre-Release"
+name: "Universal: Pre-Release"
-
+
-on:
+on:
-  workflow_dispatch:
+  pull_request:
-    inputs:
+    types: [closed]
-      stability:
+    branches:
-        description: 'Pre-release channel'
+      - dev
-        required: true
+  pull_request_target:
-        type: choice
+    types: [synchronize, opened, reopened]
-        options:
+    branches:
-          - development
+      - main
-          - alpha
+  workflow_dispatch:
-          - beta
+    inputs:
-          - release-candidate
+      stability:
-
+        description: 'Pre-release channel'
-permissions:
+        required: true
-  contents: write
+        type: choice
-
+        options:
-env:
+          - development
-  GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
+          - alpha
-  GITEA_ORG: ${{ vars.GITEA_ORG || github.repository_owner }}
+          - beta
-  GITEA_REPO: ${{ vars.GITEA_REPO || github.event.repository.name }}
+          - release-candidate
-
+
-jobs:
+permissions:
-  build:
+  contents: write
-    name: "Build Pre-Release (${{ inputs.stability }})"
+
-    runs-on: release
+env:
-
+  GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
-    steps:
+  GITEA_ORG: ${{ vars.GITEA_ORG || github.repository_owner }}
-      - name: Checkout
+  GITEA_REPO: ${{ vars.GITEA_REPO || github.event.repository.name }}
-        uses: actions/checkout@v4
+
-        with:
+jobs:
-          fetch-depth: 0
+  build:
-          token: ${{ secrets.GA_TOKEN }}
+    name: "Build Pre-Release (${{ inputs.stability || 'development' }})"
-
+    runs-on: release
-      - name: Setup PHP
+    if: >-
-        run: |
+      github.event_name == 'workflow_dispatch' ||
-          if ! command -v php &> /dev/null; then
+      (github.event_name == 'pull_request' && github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'dev') ||
-            sudo apt-get update -qq
+      (github.event_name == 'pull_request_target' && github.event.pull_request.base.ref == 'main')
-            sudo apt-get install -y -qq php-cli php-mbstring php-xml php-zip php-curl >/dev/null 2>&1
+
-          fi
+    steps:
-
+      - name: Checkout
-      - name: Setup moko-platform tools
+        uses: actions/checkout@v4
-        env:
+        with:
-          MOKO_CLONE_TOKEN: ${{ secrets.GA_TOKEN }}
+          fetch-depth: 0
-          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
+          token: ${{ secrets.MOKOGITEA_TOKEN }}
-        run: |
+          ref: ${{ github.event_name == 'pull_request_target' && github.event.pull_request.head.sha || '' }}
-          git clone --depth 1 --branch main --quiet             "https://x-access-token:${MOKO_CLONE_TOKEN}@${MOKO_CLONE_HOST}/moko-platform.git"             /tmp/moko-platform-api
+
-
+      - name: Setup moko-platform tools
-      - name: Detect platform
+        env:
-        id: platform
+          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
-        run: |
+          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
-          php /tmp/moko-platform-api/cli/manifest_read.php --path . --github-output
+        run: |
-
+          # Use pre-installed /opt/moko-platform if available (updated by cron every 6h)
-      - name: Resolve metadata
+          if [ -f /opt/moko-platform/cli/version_bump.php ] && [ -f /opt/moko-platform/cli/manifest_element.php ] && [ -f /opt/moko-platform/vendor/autoload.php ]; then
-        id: meta
+            echo Using pre-installed /opt/moko-platform
-        run: |
+            echo MOKO_CLI=/opt/moko-platform/cli >> $GITHUB_ENV
-          STABILITY="${{ inputs.stability }}"
+          else
-          MOKO_API="/tmp/moko-platform-api/cli"
+            echo Falling back to fresh clone
-
+            if ! command -v composer > /dev/null 2>&1; then
-          case "$STABILITY" in
+              sudo apt-get update -qq && sudo apt-get install -y -qq php-cli php-mbstring php-xml php-zip php-curl composer > /dev/null 2>&1
-            development)        SUFFIX="-dev";   TAG="development" ;;
+            fi
-            alpha)              SUFFIX="-alpha"; TAG="alpha" ;;
+            rm -rf /tmp/moko-platform-api
-            beta)               SUFFIX="-beta";  TAG="beta" ;;
+            CLONE_URL=https://x-access-token:${MOKO_CLONE_TOKEN}@${MOKO_CLONE_HOST}/moko-platform.git
-            release-candidate)  SUFFIX="-rc";    TAG="release-candidate" ;;
+            git clone --depth 1 --branch main --quiet $CLONE_URL /tmp/moko-platform-api
-          esac
+            cd /tmp/moko-platform-api && composer install --no-dev --no-interaction --quiet
-
+            echo MOKO_CLI=/tmp/moko-platform-api/cli >> $GITHUB_ENV
-          # Bump patch version
+          fi
-          BUMP_OUTPUT=$(php ${MOKO_API}/version_bump.php --path .)
+
-          VERSION=$(echo "$BUMP_OUTPUT" | grep -oP '\d{2}\.\d{2}\.\d{2}$' || true)
+      - name: Detect platform
-          [ -z "$VERSION" ] && VERSION=$(php ${MOKO_API}/version_read.php --path .)
+        id: platform
-          echo "Version: ${VERSION}"
+        run: |
-
+          php ${MOKO_CLI}/manifest_read.php --path . --github-output
-          # Update platform-specific manifest
+
-          php ${MOKO_API}/version_set_platform.php --path . --version "${VERSION}"
+      - name: Resolve metadata and bump version
-
+        id: meta
-          # Commit version bump
+        run: |
-          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
+          # Auto-detect stability: RC for PRs targeting main, else use input or default to development
-          git config --local user.name "gitea-actions[bot]"
+          if [ "${{ github.event_name }}" = "pull_request_target" ] && [ "${{ github.event.pull_request.base.ref }}" = "main" ]; then
-          git remote set-url origin "https://jmiller:${{ secrets.GA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"
+            STABILITY="release-candidate"
-          git add -A
+          else
-          git diff --cached --quiet || {
+            STABILITY="${{ inputs.stability || 'development' }}"
-            git commit -m "chore(version): bump to ${VERSION} [skip ci]"
+          fi
-            git push origin HEAD 2>&1
+
-          }
+          case "$STABILITY" in
-
+            development)        SUFFIX="-dev";   TAG="development" ;;
-          # Detect element from Joomla/Dolibarr manifest
+            alpha)              SUFFIX="-alpha"; TAG="alpha" ;;
-          PLATFORM="${{ steps.platform.outputs.platform }}"
+            beta)               SUFFIX="-beta";  TAG="beta" ;;
-          EXT_ELEMENT=$(php ${MOKO_API}/manifest_read.php --path . --field name 2>/dev/null | tr -d ' ' | tr '[:upper:]' '[:lower:]' || true)
+            release-candidate)  SUFFIX="-rc";    TAG="release-candidate" ;;
-          # For Joomla, prefer <element> tag
+          esac
-          if [ "$PLATFORM" = "joomla" ]; then
+
-            MANIFEST=$(find . -maxdepth 3 -name "*.xml" ! -path "./.git/*" -exec grep -l '<extension' {} \; 2>/dev/null | head -1 || true)
+          # Bump version via CLI: patch for dev/alpha/beta, minor for RC
-            if [ -n "$MANIFEST" ]; then
+          case "$STABILITY" in
-              ELEM=$(grep -oP "<element>\K[^<]+" "$MANIFEST" 2>/dev/null | head -1)
+            release-candidate) BUMP="minor" ;;
-              [ -n "$ELEM" ] && EXT_ELEMENT="$ELEM"
+            *)                 BUMP="patch" ;;
-            fi
+          esac
-          fi
+
-          [ -z "$EXT_ELEMENT" ] && EXT_ELEMENT=$(echo "${GITEA_REPO}" | tr '[:upper:]' '[:lower:]' | tr -d ' -')
+          php ${MOKO_CLI}/version_bump.php --path . $([ "$BUMP" = "minor" ] && echo "--minor") 2>/dev/null || true
-
+
-          ZIP_NAME="${EXT_ELEMENT}-${VERSION}${SUFFIX}.zip"
+          # Set stability suffix and verify consistency
-
+          VERSION=$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null || echo "00.00.01")
-          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          VERSION=$(echo "$VERSION" | sed 's/-\(dev\|alpha\|beta\|rc\)$//')
-          echo "stability=${STABILITY}" >> "$GITHUB_OUTPUT"
+
-          echo "suffix=${SUFFIX}" >> "$GITHUB_OUTPUT"
+          php ${MOKO_CLI}/version_set_platform.php \
-          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+            --path . --version "$VERSION" --branch "${{ github.ref_name }}" --stability "$STABILITY" 2>/dev/null || true
-          echo "zip_name=${ZIP_NAME}" >> "$GITHUB_OUTPUT"
+          php ${MOKO_CLI}/version_check.php --path . --fix 2>/dev/null || true
-          echo "ext_element=${EXT_ELEMENT}" >> "$GITHUB_OUTPUT"
+
-
+          # Ensure licensing tags (updateservers, dlid) if enabled in manifest.xml
-          echo "=== Pre-Release: ${EXT_ELEMENT} ${VERSION}${SUFFIX} ==="
+          php ${MOKO_CLI}/manifest_licensing.php --path . --fix 2>/dev/null || true
-
+
-      - name: Build package
+          # Append suffix for output
-        id: zip
+          if [ -n "$SUFFIX" ]; then
-        run: |
+            VERSION="${VERSION}${SUFFIX}"
-          VERSION="${{ steps.meta.outputs.version }}"
+          fi
-          SUFFIX="${{ steps.meta.outputs.suffix }}"
+
-          PLATFORM="${{ steps.platform.outputs.platform }}"
+          # Commit version bump
-
+          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
-          if [ "$PLATFORM" = "joomla" ]; then
+          git config --local user.name "gitea-actions[bot]"
-            php /tmp/moko-platform-api/cli/joomla_build.php               --path . --version "${VERSION}" --suffix "${SUFFIX}"               --output build --github-output
+          git remote set-url origin "https://x-access-token:${{ secrets.MOKOGITEA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"
-          else
+          git add -A
-            # Generic build: zip src/ directory
+          git diff --cached --quiet || {
-            SOURCE_DIR="src"
+            git commit -m "chore(version): pre-release bump to ${VERSION} [skip ci]"
-            [ ! -d "$SOURCE_DIR" ] && SOURCE_DIR="htdocs"
+            git push origin HEAD 2>&1
-            [ ! -d "$SOURCE_DIR" ] && { echo "::error::No src/ or htdocs/"; exit 1; }
+          }
-            EXT_ELEMENT="${{ steps.meta.outputs.ext_element }}"
+
-            ZIP_NAME="${EXT_ELEMENT}-${VERSION}${SUFFIX}.zip"
+          # Auto-detect element via manifest_element.php
-            mkdir -p build
+          php ${MOKO_CLI}/manifest_element.php \
-            cd "$SOURCE_DIR" && zip -r "../build/${ZIP_NAME}" . && cd ..
+            --path . --version "$VERSION" --stability "$STABILITY" \
-            SHA256=$(sha256sum "build/${ZIP_NAME}" | cut -d' ' -f1)
+            --repo "${GITEA_REPO}" --github-output
-            echo "zip_name=${ZIP_NAME}" >> "$GITHUB_OUTPUT"
+
-            echo "zip_path=build/${ZIP_NAME}" >> "$GITHUB_OUTPUT"
+          # Read back element outputs
-            echo "sha256=${SHA256}" >> "$GITHUB_OUTPUT"
+          EXT_ELEMENT=$(grep '^ext_element=' "$GITHUB_OUTPUT" | tail -1 | cut -d= -f2)
-          fi
+          ZIP_NAME=$(grep '^zip_name=' "$GITHUB_OUTPUT" | tail -1 | cut -d= -f2)
-
+          [ -z "$EXT_ELEMENT" ] && EXT_ELEMENT=$(echo "${GITEA_REPO}" | tr '[:upper:]' '[:lower:]' | tr -d ' -')
-      - name: Create or replace Gitea release
+          [ -z "$ZIP_NAME" ] && ZIP_NAME="${EXT_ELEMENT}-${VERSION}.zip"
-        id: release
+
-        continue-on-error: true
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
-        run: |
+          echo "stability=${STABILITY}" >> "$GITHUB_OUTPUT"
-          TAG="${{ steps.meta.outputs.tag }}"
+          echo "suffix=${SUFFIX}" >> "$GITHUB_OUTPUT"
-          VERSION="${{ steps.meta.outputs.version }}"
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
-          STABILITY="${{ steps.meta.outputs.stability }}"
+          echo "zip_name=${ZIP_NAME}" >> "$GITHUB_OUTPUT"
-          SHA256="${{ steps.zip.outputs.sha256 }}"
+          echo "ext_element=${EXT_ELEMENT}" >> "$GITHUB_OUTPUT"
-          ZIP_NAME="${{ steps.zip.outputs.zip_name }}"
+
-          EXT_ELEMENT="${{ steps.meta.outputs.ext_element }}"
+          echo "=== Pre-Release: ${EXT_ELEMENT} ${VERSION}${SUFFIX} ==="
-          TOKEN="${{ secrets.GA_TOKEN }}"
+
-          API="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+      - name: Create release
-          BRANCH=$(git branch --show-current)
+        id: release
-
+        run: |
-          BODY="## ${VERSION} ($(date +%Y-%m-%d))
+          TAG="${{ steps.meta.outputs.tag }}"
-          **Channel:** ${STABILITY}
+          VERSION="${{ steps.meta.outputs.version }}"
-          **SHA-256:** \`${SHA256}\`"
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-
+          php ${MOKO_CLI}/release_create.php \
-          # Delete existing release
+            --path . --version "$VERSION" --tag "$TAG" \
-          EXISTING_ID=$(curl -sS -H "Authorization: token ${TOKEN}" \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}" --api-base "$API_BASE" \
-            "${API}/releases/tags/${TAG}" | jq -r '.id // empty' 2>/dev/null)
+            --repo "${GITEA_REPO}" --branch dev --prerelease
-          if [ -n "$EXISTING_ID" ]; then
+
-            curl -sS -X DELETE -H "Authorization: token ${TOKEN}" \
+      - name: Update release notes from CHANGELOG.md
-              "${API}/releases/${EXISTING_ID}" 2>/dev/null || true
+        run: |
-            curl -sS -X DELETE -H "Authorization: token ${TOKEN}" \
+          TAG="${{ steps.meta.outputs.tag }}"
-              "${API}/tags/${TAG}" 2>/dev/null || true
+          VERSION="${{ steps.meta.outputs.version }}"
-          fi
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-
+
-          # Create release
+          # Extract [Unreleased] section from changelog (everything between [Unreleased] and next ## heading)
-          RELEASE_ID=$(curl -sS -X POST -H "Authorization: token ${TOKEN}" \
+          if [ -f "CHANGELOG.md" ]; then
-            -H "Content-Type: application/json" \
+            NOTES=$(awk '/^## \[Unreleased\]/{found=1; next} /^## \[/{if(found) exit} found{print}' CHANGELOG.md)
-            "${API}/releases" \
+            [ -z "$NOTES" ] && NOTES="Release ${VERSION}"
-            -d "$(jq -n \
+          else
-              --arg tag "$TAG" \
+            NOTES="Release ${VERSION}"
-              --arg target "$BRANCH" \
+          fi
-              --arg name "${EXT_ELEMENT} ${VERSION} (${STABILITY})" \
+
-              --arg body "$BODY" \
+          # Update release body via API
-              '{tag_name: $tag, target_commitish: $target, name: $name, body: $body, prerelease: true}'
+          RELEASE_ID=$(curl -sf -H "Authorization: token ${{ secrets.MOKOGITEA_TOKEN }}" \
-            )" | jq -r '.id')
+            "${API_BASE}/releases/tags/${TAG}" | python3 -c "import json,sys; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || true)
-
+
-          echo "release_id=${RELEASE_ID}" >> "$GITHUB_OUTPUT"
+          if [ -n "$RELEASE_ID" ]; then
-
+            python3 -c "
-          # Upload ZIP
+          import json, urllib.request
-          curl -sS -X POST -H "Authorization: token ${TOKEN}" \
+          body = open('/dev/stdin').read()
-            -H "Content-Type: application/octet-stream" \
+          payload = json.dumps({'body': body}).encode()
-            "${API}/releases/${RELEASE_ID}/assets?name=${ZIP_NAME}" \
+          req = urllib.request.Request(
-            --data-binary "@${{ steps.zip.outputs.zip_path }}"
+              '${API_BASE}/releases/${RELEASE_ID}',
-
+              data=payload, method='PATCH',
-          echo "Released: ${EXT_ELEMENT} ${VERSION} (${STABILITY})"
+              headers={
-
+                  'Authorization': 'token ${{ secrets.MOKOGITEA_TOKEN }}',
-      - name: "Update updates.xml"
+                  'Content-Type': 'application/json'
-        if: steps.platform.outputs.platform == 'joomla'
+              })
-        run: |
+          urllib.request.urlopen(req)
-          VERSION="${{ steps.meta.outputs.version }}"
+          " <<< "$NOTES"
-          STABILITY="${{ steps.meta.outputs.stability }}"
+            echo "Release notes updated from CHANGELOG.md"
-          SHA256="${{ steps.zip.outputs.sha256 }}"
+          fi
-          php /tmp/moko-platform-api/cli/updates_xml_build.php             --path . --version "$VERSION" --stability "$STABILITY"             --sha "$SHA256"             --gitea-url "$GITEA_URL" --org "$GITEA_ORG" --repo "$GITEA_REPO"
+
-          if ! git diff --quiet updates.xml 2>/dev/null; then
+      - name: Build package and upload
-            git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
+        id: package
-            git config --local user.name "gitea-actions[bot]"
+        run: |
-            git add updates.xml
+          VERSION="${{ steps.meta.outputs.version }}"
-            git commit -m "chore: update $STABILITY channel $VERSION [skip ci]"
+          TAG="${{ steps.meta.outputs.tag }}"
-            git push origin HEAD 2>&1 || echo "WARNING: push failed"
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-          fi
+          php ${MOKO_CLI}/release_package.php \
-
+            --path . --version "$VERSION" --tag "$TAG" \
-      - name: "Sync updates.xml to all branches"
+            --token "${{ secrets.MOKOGITEA_TOKEN }}" --api-base "$API_BASE" \
-        if: steps.platform.outputs.platform == 'joomla'
+            --repo "${GITEA_REPO}" --output /tmp || true
-        run: |
+
-          php /tmp/moko-platform-api/cli/updates_xml_sync.php             --path .             --current "${{ github.ref_name }}"             --branches main,dev             --version "${{ steps.meta.outputs.version }}"             --token "${{ secrets.GA_TOKEN }}"             --org "${GITEA_ORG}"             --repo "${GITEA_REPO}"             --gitea-url "${GITEA_URL}"
+      # updates.xml is generated dynamically by MokoGitea license server
-
+      # No need to build, commit, or sync updates.xml from workflows
-      - name: "Delete lesser pre-release channels (cascade)"
+
-        continue-on-error: true
+      - name: "Delete lesser pre-release channels (cascade)"
-        run: |
+        continue-on-error: true
-          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+        run: |
-          TOKEN="${{ secrets.GA_TOKEN }}"
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-          STABILITY="${{ steps.meta.outputs.stability }}"
+          TOKEN="${{ secrets.MOKOGITEA_TOKEN }}"
-
+
-          # Cascade: rc → beta,alpha,dev | beta → alpha,dev | alpha → dev | dev → nothing
+          php ${MOKO_CLI}/release_cascade.php \
-          case "$STABILITY" in
+            --stability "${{ steps.meta.outputs.stability }}" \
-            release-candidate) TAGS_TO_DELETE="beta alpha development" ;;
+            --token "${TOKEN}" \
-            beta)              TAGS_TO_DELETE="alpha development" ;;
+            --api-base "${API_BASE}"
-            alpha)             TAGS_TO_DELETE="development" ;;
+
-            *)                 TAGS_TO_DELETE="" ;;
+      - name: Summary
-          esac
+        if: always()
-
+        run: |
-          [ -z "$TAGS_TO_DELETE" ] && exit 0
+          VERSION="${{ steps.meta.outputs.version }}"
-
+          STABILITY="${{ steps.meta.outputs.stability }}"
-          for TAG in $TAGS_TO_DELETE; do
+          ZIP_NAME="${{ steps.meta.outputs.zip_name }}"
-            RELEASE_ID=$(curl -sS -H "Authorization: token ${TOKEN}" \
+          SHA256="${{ steps.package.outputs.sha256_zip }}"
-              "${API_BASE}/releases/tags/${TAG}" 2>/dev/null | \
+          echo "## Pre-Release Complete" >> $GITHUB_STEP_SUMMARY
-              python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || true)
+          echo "" >> $GITHUB_STEP_SUMMARY
-
+          echo "| Field | Value |" >> $GITHUB_STEP_SUMMARY
-            if [ -n "$RELEASE_ID" ] && [ "$RELEASE_ID" != "None" ]; then
+          echo "|-------|-------|" >> $GITHUB_STEP_SUMMARY
-              curl -sS -X DELETE -H "Authorization: token ${TOKEN}" \
+          echo "| Version | \`${VERSION}\` |" >> $GITHUB_STEP_SUMMARY
-                "${API_BASE}/releases/${RELEASE_ID}" 2>/dev/null || true
+          echo "| Channel | ${STABILITY} |" >> $GITHUB_STEP_SUMMARY
-              curl -sS -X DELETE -H "Authorization: token ${TOKEN}" \
+          echo "| Package | \`${ZIP_NAME}\` |" >> $GITHUB_STEP_SUMMARY
-                "${API_BASE}/tags/${TAG}" 2>/dev/null || true
+          echo "| SHA-256 | \`${SHA256:-n/a}\` |" >> $GITHUB_STEP_SUMMARY
-              echo "Deleted: ${TAG} (id: ${RELEASE_ID})"
-            fi
-          done

CHANGELOG.md

@@ -1,128 +1,11 @@
-<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
-SPDX-License-Identifier: GPL-3.0-or-later
-DEFGROUP: gitea-api-mcp.Documentation
-REPO: https://git.mokoconsulting.tech/MokoConsulting/gitea-api-mcp
--->
 
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
 ### Changed
-- **Renamed** package from `@mokoconsulting/gitea-api-mcp` to `@mokoconsulting/mokogitea-api-mcp` to distinguish Moko's forked Gitea MCP from upstream
+- Migrated all workflow and template paths from `.github/` to `.mokogitea/`
-- **Renamed** McpServer name and bin entry to `mokogitea-api-mcp`
+- Template source paths updated: `templates/gitea/` to `templates/mokogitea/`
-
+- HCL definition files removed -- Template repos are now the canonical source
-## [0.0.1] - 2026-05-07
 
 ### Added
-
+- `branch-cleanup.yml`: auto-delete merged feature branches after PR merge
-#### User / Auth (3 tools)
-- `gitea_me` -- Get the authenticated user info
-- `gitea_user_orgs` -- List organizations the authenticated user belongs to
-- `gitea_user_repos` -- List repositories owned by the authenticated user
-
-#### Repositories (8 tools)
-- `gitea_repo_get` -- Get repository details
-- `gitea_repo_create` -- Create a new repository
-- `gitea_repo_delete` -- Delete a repository
-- `gitea_repo_edit` -- Edit repository settings
-- `gitea_repo_fork` -- Fork a repository
-- `gitea_repo_search` -- Search repositories
-- `gitea_org_repos` -- List repositories in an organization
-- `gitea_list_connections` -- List configured Gitea connections
-
-#### File Contents (5 tools)
-- `gitea_file_get` -- Get file contents from a repository
-- `gitea_dir_get` -- Get directory contents (file listing) from a repository
-- `gitea_file_create_or_update` -- Create or update a file in a repository
-- `gitea_file_delete` -- Delete a file from a repository
-- `gitea_tree_get` -- Get the git tree for a repository (recursive file listing)
-
-#### Branches (4 tools)
-- `gitea_branches_list` -- List branches in a repository
-- `gitea_branch_get` -- Get a specific branch
-- `gitea_branch_create` -- Create a new branch
-- `gitea_branch_delete` -- Delete a branch
-
-#### Commits (2 tools)
-- `gitea_commits_list` -- List commits in a repository
-- `gitea_commit_get` -- Get a specific commit
-
-#### Issues (7 tools)
-- `gitea_issues_list` -- List issues in a repository
-- `gitea_issue_get` -- Get a single issue by number
-- `gitea_issue_create` -- Create a new issue
-- `gitea_issue_update` -- Update an issue
-- `gitea_issue_comments_list` -- List comments on an issue
-- `gitea_issue_comment_create` -- Add a comment to an issue
-- `gitea_issue_search` -- Search issues across all repositories
-
-#### Labels (2 tools)
-- `gitea_labels_list` -- List labels in a repository
-- `gitea_label_create` -- Create a label
-
-#### Milestones (2 tools)
-- `gitea_milestones_list` -- List milestones in a repository
-- `gitea_milestone_create` -- Create a milestone
-
-#### Pull Requests (6 tools)
-- `gitea_pulls_list` -- List pull requests
-- `gitea_pull_get` -- Get a single pull request
-- `gitea_pull_create` -- Create a pull request
-- `gitea_pull_merge` -- Merge a pull request
-- `gitea_pull_files` -- List files changed in a pull request
-- `gitea_pull_review_create` -- Create a pull request review
-
-#### Releases (5 tools)
-- `gitea_releases_list` -- List releases
-- `gitea_release_get` -- Get a single release by ID
-- `gitea_release_latest` -- Get the latest release
-- `gitea_release_create` -- Create a new release
-- `gitea_release_delete` -- Delete a release
-
-#### Tags (3 tools)
-- `gitea_tags_list` -- List tags
-- `gitea_tag_create` -- Create a tag
-- `gitea_tag_delete` -- Delete a tag
-
-#### Actions (2 tools)
-- `gitea_actions_runs_list` -- List workflow runs for a repository
-- `gitea_actions_run_get` -- Get a specific workflow run
-
-#### Organizations (3 tools)
-- `gitea_org_get` -- Get organization details
-- `gitea_org_teams_list` -- List teams in an organization
-- `gitea_org_members_list` -- List members of an organization
-
-#### Users (2 tools)
-- `gitea_user_get` -- Get a user profile
-- `gitea_users_search` -- Search users
-
-#### Webhooks (2 tools)
-- `gitea_webhooks_list` -- List webhooks for a repository
-- `gitea_webhook_create` -- Create a webhook
-
-#### Wiki (2 tools)
-- `gitea_wiki_pages_list` -- List wiki pages
-- `gitea_wiki_page_get` -- Get a wiki page
-
-#### Notifications (2 tools)
-- `gitea_notifications_list` -- List notifications for the authenticated user
-- `gitea_notifications_read` -- Mark all notifications as read
-
-#### Generic (2 tools)
-- `gitea_api_request` -- Make a raw API request to any Gitea v1 endpoint
-- `gitea_list_connections` -- List configured Gitea connections
-
-### Infrastructure
-- Multi-connection config support via `~/.gitea-api-mcp.json`
-- Token-based authentication (Gitea native `Authorization: token` header)
-- Built on `node:https` / `node:http` (zero HTTP dependencies)
-- MCP SDK v1.12.x with stdio transport
-
-[0.0.1]: https://git.mokoconsulting.tech/MokoConsulting/gitea-api-mcp/releases/tag/v0.0.1

automation/ci-issue-reporter.sh

@@ -0,0 +1,237 @@
+#!/usr/bin/env bash
+# ============================================================================
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# FILE INFORMATION
+# DEFGROUP: Automation.CI
+# INGROUP: moko-platform.Automation
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+# PATH: /automation/ci-issue-reporter.sh
+# VERSION: 09.23.00
+# BRIEF: Creates or updates a Gitea issue when a CI gate fails.
+#        Deduplicates by searching open issues with the "ci-auto" label
+#        whose title matches the gate. If a matching issue exists, a comment
+#        is appended instead of opening a duplicate.
+# ============================================================================
+
+set -euo pipefail
+
+# ── Defaults ────────────────────────────────────────────────────────────────
+GITEA_URL="${GITEA_URL:-https://git.mokoconsulting.tech}"
+GITEA_TOKEN="${GITEA_TOKEN:-}"
+REPO="${GITHUB_REPOSITORY:-}"
+RUN_URL="${GITHUB_SERVER_URL:-${GITEA_URL}}/${REPO}/actions/runs/${GITHUB_RUN_ID:-0}"
+LABEL_NAME="ci-auto"
+LABEL_COLOR="#e11d48"
+
+GATE=""
+DETAILS=""
+SEVERITY="error"
+WORKFLOW=""
+
+# ── Parse arguments ─────────────────────────────────────────────────────────
+usage() {
+  cat <<EOF
+Usage: ci-issue-reporter.sh --gate NAME --details TEXT [OPTIONS]
+
+Required:
+  --gate      CI gate name (e.g. "Code Quality", "Self-Health")
+  --details   Human-readable failure description
+
+Optional:
+  --severity  "error" (default) or "warning"
+  --workflow  Workflow name for the issue title
+  --repo      owner/repo (default: \$GITHUB_REPOSITORY)
+  --run-url   URL to the CI run (auto-detected from env)
+  --token     Gitea API token (default: \$GITEA_TOKEN)
+  --url       Gitea base URL (default: \$GITEA_URL)
+EOF
+  exit 1
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --gate)     GATE="$2";       shift 2 ;;
+    --details)  DETAILS="$2";    shift 2 ;;
+    --severity) SEVERITY="$2";   shift 2 ;;
+    --workflow) WORKFLOW="$2";   shift 2 ;;
+    --repo)     REPO="$2";      shift 2 ;;
+    --run-url)  RUN_URL="$2";   shift 2 ;;
+    --token)    GITEA_TOKEN="$2"; shift 2 ;;
+    --url)      GITEA_URL="$2"; shift 2 ;;
+    -h|--help)  usage ;;
+    *)          echo "Unknown option: $1"; usage ;;
+  esac
+done
+
+[[ -z "$GATE" ]]         && { echo "ERROR: --gate is required"; usage; }
+[[ -z "$DETAILS" ]]      && { echo "ERROR: --details is required"; usage; }
+[[ -z "$GITEA_TOKEN" ]]  && { echo "ERROR: GITEA_TOKEN not set"; exit 1; }
+[[ -z "$REPO" ]]         && { echo "ERROR: GITHUB_REPOSITORY not set"; exit 1; }
+
+API="${GITEA_URL}/api/v1/repos/${REPO}"
+
+# ── Build title ─────────────────────────────────────────────────────────────
+if [[ -n "$WORKFLOW" ]]; then
+  TITLE="[CI] ${WORKFLOW}: ${GATE} failed"
+else
+  TITLE="[CI] ${GATE} failed"
+fi
+
+# ── Ensure label exists ─────────────────────────────────────────────────────
+ensure_label() {
+  local exists
+  exists=$(curl -sf -o /dev/null -w '%{http_code}' \
+    -H "Authorization: token ${GITEA_TOKEN}" \
+    "${API}/labels" 2>/dev/null || echo "000")
+
+  if [[ "$exists" == "200" ]]; then
+    # Check if label already exists
+    local found
+    found=$(curl -sf \
+      -H "Authorization: token ${GITEA_TOKEN}" \
+      "${API}/labels" 2>/dev/null \
+      | grep -o "\"name\":\"${LABEL_NAME}\"" || true)
+
+    if [[ -z "$found" ]]; then
+      curl -sf -X POST \
+        -H "Authorization: token ${GITEA_TOKEN}" \
+        -H "Content-Type: application/json" \
+        "${API}/labels" \
+        -d "{\"name\":\"${LABEL_NAME}\",\"color\":\"${LABEL_COLOR}\",\"description\":\"Auto-created by CI issue reporter\"}" \
+        > /dev/null 2>&1 || true
+    fi
+  fi
+}
+
+# ── Search for existing open issue ──────────────────────────────────────────
+find_existing_issue() {
+  # URL-encode the gate name for the query
+  local query
+  query=$(printf '%s' "[CI] ${GATE}" | sed 's/ /%20/g; s/\[/%5B/g; s/\]/%5D/g')
+
+  local response
+  response=$(curl -sf \
+    -H "Authorization: token ${GITEA_TOKEN}" \
+    "${API}/issues?type=issues&state=open&labels=${LABEL_NAME}&q=${query}&limit=5" \
+    2>/dev/null || echo "[]")
+
+  # Extract the first matching issue number
+  echo "$response" \
+    | grep -oP '"number":\s*\K[0-9]+' \
+    | head -1
+}
+
+# ── Build issue body ────────────────────────────────────────────────────────
+build_body() {
+  local severity_badge
+  if [[ "$SEVERITY" == "error" ]]; then
+    severity_badge="**Severity:** Error"
+  else
+    severity_badge="**Severity:** Warning"
+  fi
+
+  cat <<BODY
+## CI Gate Failure: ${GATE}
+
+${severity_badge}
+**Workflow:** ${WORKFLOW:-unknown}
+**Branch:** ${GITHUB_REF_NAME:-unknown}
+**Commit:** \`${GITHUB_SHA:0:8}\`
+**Run:** [View CI run](${RUN_URL})
+
+### Details
+
+${DETAILS}
+
+### Resolution
+
+Fix the issue described above and push a new commit. This issue will be closed automatically when the gate passes, or can be closed manually.
+
+---
+*Auto-created by [ci-issue-reporter](${GITEA_URL}/${REPO}/src/branch/main/automation/ci-issue-reporter.sh)*
+BODY
+}
+
+# ── Build comment body (for existing issues) ────────────────────────────────
+build_comment() {
+  cat <<COMMENT
+### CI failure recurrence
+
+**Branch:** ${GITHUB_REF_NAME:-unknown}
+**Commit:** \`${GITHUB_SHA:0:8}\`
+**Run:** [View CI run](${RUN_URL})
+
+${DETAILS}
+COMMENT
+}
+
+# ── Main ────────────────────────────────────────────────────────────────────
+ensure_label
+
+EXISTING=$(find_existing_issue)
+
+if [[ -n "$EXISTING" ]]; then
+  # Append comment to existing issue
+  COMMENT_BODY=$(build_comment)
+  COMMENT_JSON=$(printf '%s' "$COMMENT_BODY" | python3 -c "
+import sys, json
+print(json.dumps({'body': sys.stdin.read()}))" 2>/dev/null)
+
+  HTTP=$(curl -sf -o /dev/null -w '%{http_code}' -X POST \
+    -H "Authorization: token ${GITEA_TOKEN}" \
+    -H "Content-Type: application/json" \
+    "${API}/issues/${EXISTING}/comments" \
+    -d "${COMMENT_JSON}" 2>/dev/null || echo "000")
+
+  if [[ "$HTTP" == "201" ]]; then
+    echo "Commented on existing issue #${EXISTING}"
+  else
+    echo "WARNING: Failed to comment on issue #${EXISTING} (HTTP ${HTTP})"
+  fi
+else
+  # Create new issue
+  ISSUE_BODY=$(build_body)
+  ISSUE_JSON=$(python3 -c "
+import sys, json
+body = sys.stdin.read()
+print(json.dumps({
+    'title': sys.argv[1],
+    'body': body,
+    'labels': []
+}))" "$TITLE" <<< "$ISSUE_BODY" 2>/dev/null)
+
+  # Create the issue
+  RESPONSE=$(curl -sf -X POST \
+    -H "Authorization: token ${GITEA_TOKEN}" \
+    -H "Content-Type: application/json" \
+    "${API}/issues" \
+    -d "${ISSUE_JSON}" 2>/dev/null || echo "{}")
+
+  ISSUE_NUM=$(echo "$RESPONSE" | grep -oP '"number":\s*\K[0-9]+' | head -1)
+
+  if [[ -n "$ISSUE_NUM" ]]; then
+    # Apply label (separate call — more reliable across Gitea versions)
+    LABEL_ID=$(curl -sf \
+      -H "Authorization: token ${GITEA_TOKEN}" \
+      "${API}/labels" 2>/dev/null \
+      | grep -oP "\"id\":\s*\K[0-9]+(?=[^}]*\"name\":\s*\"${LABEL_NAME}\")" \
+      | head -1 || true)
+
+    if [[ -n "$LABEL_ID" ]]; then
+      curl -sf -X POST \
+        -H "Authorization: token ${GITEA_TOKEN}" \
+        -H "Content-Type: application/json" \
+        "${API}/issues/${ISSUE_NUM}/labels" \
+        -d "{\"labels\":[${LABEL_ID}]}" \
+        > /dev/null 2>&1 || true
+    fi
+
+    echo "Created issue #${ISSUE_NUM}: ${TITLE}"
+  else
+    echo "WARNING: Failed to create issue"
+    echo "Response: ${RESPONSE}"
+  fi
+fi