Complete native Joomla MCP component with JCB execution and installed acceptance

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = tab
+
+[*.{yml,yaml,json,xml,md}]
+indent_style = space
+indent_size = 2

.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: PHP contracts and migration evidence
+
+on:
+  pull_request:
+  push:
+    branches: [main, feature/jcb-mcp-runtime]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: php-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  contracts:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.3', '8.4']
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: curl, json, mbstring, sodium, zip, fileinfo, pcntl, posix
+          tools: composer:v2
+          coverage: none
+      - name: Validate Composer metadata
+        run: composer validate --no-check-publish
+      - name: Install PHP dependencies
+        run: composer install --no-interaction --prefer-dist --no-progress
+      - name: PHP syntax
+        run: find . -type d \( -name vendor -o -name .git -o -name .reference -o -name build \) -prune -o -type f -name '*.php' -print0 | xargs -0 -r -n1 php -l
+      - name: Verify source-pinned seed reproducibility
+        run: |
+          set -euo pipefail
+          php tools/generate-catalogue.php
+          git diff --exit-code -- admin/sql data/catalogue-seed.json docs/migration/parity.json
+      - name: Behavioural and source-parity contracts
+        run: |
+          set -euo pipefail
+          mkdir -p build/evidence
+          for suite in run catalogue schema-shapes execution actions planned jobs process job-process jcb jcb-plan-preview protocol http ownership native/run; do
+            php "tests/$suite.php" | tee "build/evidence/${suite//\//-}.log"
+          done
+      - name: Preserve the tested PHP runtime for reproducible investigation
+        if: always() && matrix.php == '8.3'
+        run: |
+          set -euo pipefail
+          mkdir -p build
+          git rev-parse HEAD > build/tested-commit.txt
+          tar --exclude-vcs --exclude='./build' --exclude='./.reference' -czf build/tested-php-runtime.tar.gz .
+          sha256sum build/tested-php-runtime.tar.gz > build/tested-php-runtime.sha256
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: php-evidence-${{ matrix.php }}
+          path: build/
+          if-no-files-found: error
+          retention-days: 7

.github/workflows/development-runtime.yml

@@ -0,0 +1,84 @@
+name: Disposable PHP integration toolchain
+
+on:
+  push:
+    branches: [feature/jcb-mcp-runtime]
+    paths: [.github/workflows/development-runtime.yml]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  toolchain:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: curl, dom, fileinfo, gd, intl, mbstring, mysqli, pdo_mysql, pdo_pgsql, pgsql, simplexml, sodium, xml, xmlreader, xmlwriter, zip
+          tools: composer:v2
+          coverage: none
+      - name: Collect only public runtime binaries and linked libraries for offline integration testing
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [ ! -x /usr/lib/postgresql/16/bin/initdb ]; then
+            sudo apt-get update -qq
+            sudo apt-get install -y --no-install-recommends postgresql-16
+          fi
+          work="$(mktemp -d)"
+          runtime="$work/runtime"
+          mkdir -p "$runtime"/{bin,lib,php/bin,php/modules,postgresql/bin,postgresql/lib,postgresql/share}
+          cp -L "$(command -v php)" "$runtime/php/bin/php"
+          cp -L "$(command -v composer)" "$runtime/php/composer.phar"
+          extension_dir="$(php -r 'echo ini_get("extension_dir");')"
+          printf '%s\n' 'date.timezone=UTC' 'memory_limit=512M' 'display_errors=stderr' 'log_errors=0' > "$runtime/php/php.ini"
+          for module in ctype curl dom fileinfo gd iconv intl mbstring mysqlnd mysqli pdo pdo_mysql pdo_pgsql pgsql phar simplexml sodium tokenizer xml xmlreader xmlwriter zip; do
+            if [ -f "$extension_dir/$module.so" ]; then
+              cp -L "$extension_dir/$module.so" "$runtime/php/modules/$module.so"
+              printf 'extension=%s.so\n' "$module" >> "$runtime/php/php.ini"
+            fi
+          done
+          cp -a /usr/lib/postgresql/16/bin/. "$runtime/postgresql/bin/"
+          cp -a /usr/lib/postgresql/16/lib/. "$runtime/postgresql/lib/"
+          cp -a /usr/share/postgresql/16/. "$runtime/postgresql/share/"
+          find "$runtime/postgresql/lib" -type d -name bitcode -prune -exec rm -rf -- {} +
+          while IFS= read -r -d '' binary; do
+            while IFS= read -r library; do
+              case "$(basename "$library")" in
+                libc.so.*|libm.so.*|libpthread.so.*|libdl.so.*|librt.so.*|ld-linux*|libresolv.so.*|libutil.so.*) continue ;;
+              esac
+              [ -f "$library" ] && cp -L "$library" "$runtime/lib/$(basename "$library")"
+            done < <(ldd "$binary" 2>/dev/null | awk '/=> \/[a-zA-Z]/{print $3} /^\s*\/[a-zA-Z]/{print $1}' || true)
+          done < <(find "$runtime/php/bin" "$runtime/php/modules" "$runtime/postgresql/bin" "$runtime/postgresql/lib" -type f \( -name php -o -name '*.so' -o -perm /111 \) -print0)
+          cat > "$runtime/bin/php" <<'BASH'
+          #!/usr/bin/env bash
+          set -euo pipefail
+          root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
+          export LD_LIBRARY_PATH="$root/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+          export PHP_INI_SCAN_DIR=''
+          exec "$root/php/bin/php" -c "$root/php/php.ini" -d "extension_dir=$root/php/modules" "$@"
+          BASH
+          cat > "$runtime/bin/composer" <<'BASH'
+          #!/usr/bin/env bash
+          set -euo pipefail
+          root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
+          exec "$root/bin/php" "$root/php/composer.phar" "$@"
+          BASH
+          chmod +x "$runtime/bin/php" "$runtime/bin/composer"
+          "$runtime/bin/php" -v
+          "$runtime/bin/php" -m
+          "$runtime/bin/composer" --version
+          LD_LIBRARY_PATH="$runtime/lib" "$runtime/postgresql/bin/postgres" --version
+          printf '%s\n' 'Development-only runtime binaries from the GitHub Ubuntu runner and setup-php.' 'No repository, environment, credentials, database contents or runner configuration is included.' > "$runtime/NOTICE.txt"
+          mkdir -p "$RUNNER_TEMP/integration-toolchain"
+          tar -czf "$RUNNER_TEMP/integration-toolchain/runtime.tar.gz" -C "$work" runtime
+          sha256sum "$RUNNER_TEMP/integration-toolchain/runtime.tar.gz" > "$RUNNER_TEMP/integration-toolchain/runtime.sha256"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: disposable-integration-toolchain
+          path: ${{ runner.temp }}/integration-toolchain/
+          if-no-files-found: error
+          retention-days: 2

.github/workflows/generate-catalogue.yml

@@ -0,0 +1,51 @@
+name: Generate reviewed Joomla installation catalogue
+
+on:
+  push:
+    branches: [feature/jcb-mcp-runtime]
+    paths:
+      - tools/generate-catalogue.php
+      - admin/src/Database/Structure.php
+      - .github/workflows/generate-catalogue.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: generate-joomla-mcp-catalogue
+  cancel-in-progress: false
+
+jobs:
+  generate:
+    if: github.repository == 'joomengine/mcp_component' && github.ref == 'refs/heads/feature/jcb-mcp-runtime'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: true
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          coverage: none
+      - name: Generate portable SQL and the complete source-parity map
+        run: |
+          set -euo pipefail
+          php -l tools/generate-catalogue.php
+          php tools/generate-catalogue.php
+          git diff --check
+      - name: Commit only generated catalogue files to the existing PR branch
+        run: |
+          set -euo pipefail
+          git add -- admin/sql data/catalogue-seed.json docs/migration/parity.json
+          if git diff --cached --quiet; then
+            exit 0
+          fi
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git commit -m 'build: generate portable install SQL and the complete database capability graph'
+          git push origin HEAD:refs/heads/feature/jcb-mcp-runtime

.github/workflows/golden-image.yml

@@ -0,0 +1,69 @@
+name: Installed JCB golden image
+
+on:
+  pull_request:
+  push:
+    branches: [main, feature/jcb-mcp-runtime]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: jcb-installed-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  installed:
+    runs-on: ubuntu-latest
+    timeout-minutes: 40
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: curl, dom, fileinfo, intl, json, mbstring, sodium, xml, zip
+          tools: composer:v2
+          coverage: none
+      - name: Build the actual installable component
+        run: bash tools/build.sh && php tests/package.php
+      - name: Check out the JCB implementation under test
+        uses: actions/checkout@v7
+        with:
+          repository: extension-builder/joomla
+          ref: 5ee658dd07eb749dca43ed4722f6cca7eb8208cf
+          path: build/jcb-source
+          persist-credentials: false
+      - name: Check out the reviewed console plugin under test
+        uses: actions/checkout@v7
+        with:
+          repository: joomengine/mcp_plugin
+          ref: fe387b962dab605191ef18efe4d5cb94821165d9
+          path: build/plugin-source
+          persist-credentials: false
+      - name: Check out the remote client bridge under test
+        uses: actions/checkout@v7
+        with:
+          repository: joomengine/mcp_client
+          ref: 881b1006b67afc24d35d17b82cd32d16a5593a44
+          path: build/client-source
+          persist-credentials: false
+      - name: Install the client dependencies for the remote acceptance scenario
+        working-directory: build/client-source
+        run: composer install --no-interaction --prefer-dist --no-progress
+      - name: Install the component into the JCB golden image and exercise native Joomla
+        env:
+          COMPOSE_PROJECT_NAME: mcp-${{ github.run_id }}-${{ github.run_attempt }}
+          MCP_PLUGIN_SOURCE: ${{ github.workspace }}/build/plugin-source
+          MCP_CLIENT_SOURCE: ${{ github.workspace }}/build/client-source
+        run: bash tests/golden-image/run.sh
+      - name: Preserve redacted installation and execution evidence
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: installed-jcb-golden-image
+          path: build/evidence/golden/
+          retention-days: 14
+          if-no-files-found: error

.github/workflows/import-runtime.yml

@@ -0,0 +1,82 @@
+name: Import pinned PHP runtime and catalogue
+
+on:
+  push:
+    branches: [feature/jcb-mcp-runtime]
+    paths:
+      - .github/workflows/import-runtime.yml
+      - tools/migration/import-native.php
+      - tools/migration/align-native-tests.php
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: import-pinned-runtime
+  cancel-in-progress: false
+
+jobs:
+  import:
+    if: github.repository == 'joomengine/mcp_component' && github.ref == 'refs/heads/feature/jcb-mcp-runtime'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: true
+      - name: Check whether the one-time import was already committed
+        id: state
+        shell: bash
+        run: |
+          set -euo pipefail
+          if test -f data/upstream-native.json; then
+            echo 'needed=false' >> "$GITHUB_OUTPUT"
+          else
+            echo 'needed=true' >> "$GITHUB_OUTPUT"
+          fi
+      - uses: actions/checkout@v7
+        if: steps.state.outputs.needed == 'true'
+        with:
+          repository: joomengine/joomla-mcp
+          ref: 2cff50f4f6b440da3c684f9995a77efad32e1a36
+          path: .reference/joomla-mcp
+          persist-credentials: false
+      - uses: actions/setup-node@v7
+        if: steps.state.outputs.needed == 'true'
+        with:
+          node-version: 22
+      - uses: shivammathur/setup-php@v2
+        if: steps.state.outputs.needed == 'true'
+        with:
+          php-version: '8.3'
+          extensions: json, mbstring
+          coverage: none
+      - name: Export and migrate the immutable source without invoking Joomla actions
+        if: steps.state.outputs.needed == 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+          test "$(git -C .reference/joomla-mcp rev-parse HEAD)" = 2cff50f4f6b440da3c684f9995a77efad32e1a36
+          npm --prefix .reference/joomla-mcp ci --ignore-scripts --no-audit
+          npm --prefix .reference/joomla-mcp run build
+          mkdir -p data
+          node tools/migration/export-upstream.mjs .reference/joomla-mcp data/upstream-contracts.json
+          php tools/migration/import-native.php .reference/joomla-mcp .
+          php tools/migration/align-native-tests.php
+          find admin/src/Native tests/native -type f -name '*.php' -print0 | xargs -0 -n1 php -l
+          php tests/native/run.php
+          git diff --check
+      - name: Commit the verified import to this existing PR branch only
+        if: steps.state.outputs.needed == 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+          git add -- admin/src/Native tests/native data/upstream-contracts.json data/upstream-native.json docs/migration/native-source-map.json LICENSES/joomla-mcp.txt
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git commit -m 'feat: migrate pinned native PHP handlers, behavioural tests and full action contracts'
+          git push origin HEAD:refs/heads/feature/jcb-mcp-runtime