test(e2e): add container E2E suite, docs and quality CI

.devcontainer/Dockerfile

@@ -0,0 +1,82 @@
+# Copyright 2026 Han Li and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# The repository dev container (see docs/e2e.md): a Linux userland that is
+# identical on every host platform — Linux amd64/arm64 natively, Windows
+# amd64/arm64 through Docker Desktop's Linux-container mode. It carries the
+# pinned Go toolchain the E2E suites and the local checks need, matching the
+# setup-go version CI uses, plus the Lua and license tooling pinned in the
+# lint and license workflows.
+#
+# The suites themselves run testcontainers against the host daemon through
+# the socket mounted by devcontainer.json (Docker-out-of-Docker), so the
+# target containers are spawned exactly as a native CI runner spawns them.
+#
+# The image is multi-arch (linux/amd64 and linux/arm64); the Lua downloads
+# below select their asset per target arch.
+
+FROM golang:1.27.1
+
+# Docker CLI (client only): drives the host daemon from the shell, the same
+# daemon the suites drive through the Docker Go API. Engine 29 is the line
+# tests/e2e/windows/install-docker-arm64.ps1 builds for Windows arm64.
+COPY --from=docker:29-cli /usr/local/bin/docker /usr/local/bin/docker
+
+# Keep the tool versions below in step with .github/workflows/lint.yml
+# (stylua-action's version and the `mise x aqua:...` line).
+ARG STYLUA_VERSION=2.5.2
+ARG LUA_LANGUAGE_SERVER_VERSION=3.19.1
+
+# Heredocs need BuildKit, which the dev container tooling uses by default. The
+# E2E target Dockerfiles stay on the chained-`;` form: testcontainers-go's
+# build path cannot use BuildKit (see tests/e2e/linux/Dockerfile).
+
+RUN <<EOF
+set -o errexit -o nounset -o xtrace
+apt-get update
+apt-get install --assume-yes --no-install-recommends \
+    ca-certificates \
+    curl \
+    git \
+    unzip \
+    zip
+rm --recursive --force /var/lib/apt/lists/*
+case "$(dpkg --print-architecture)" in
+    amd64) stylua_asset=stylua-linux-x86_64.zip; luals_asset="lua-language-server-${LUA_LANGUAGE_SERVER_VERSION}-linux-x64.tar.gz" ;;
+    arm64) stylua_asset=stylua-linux-aarch64.zip; luals_asset="lua-language-server-${LUA_LANGUAGE_SERVER_VERSION}-linux-arm64.tar.gz" ;;
+    *) echo "FAIL unsupported architecture $(dpkg --print-architecture)" >&2; exit 1 ;;
+esac
+curl --fail --silent --show-error --location --output /tmp/stylua.zip \
+    "https://github.com/JohnnyMorganz/StyLua/releases/download/v${STYLUA_VERSION}/${stylua_asset}"
+unzip -q /tmp/stylua.zip -d /usr/local/bin
+rm --force /tmp/stylua.zip
+curl --fail --silent --show-error --location --output /tmp/luals.tar.gz \
+    "https://github.com/LuaLS/lua-language-server/releases/download/${LUA_LANGUAGE_SERVER_VERSION}/${luals_asset}"
+mkdir --parents /opt/lua-language-server
+tar --extract --gzip --file /tmp/luals.tar.gz --directory /opt/lua-language-server
+rm --force /tmp/luals.tar.gz
+ln --symbolic /opt/lua-language-server/bin/lua-language-server /usr/local/bin/lua-language-server
+stylua --version
+lua-language-server --version
+EOF
+
+# License-header tooling at the versions pinned by .github/workflows/license.yml
+# (SkyWalking Eyes v0.9.0 for the header check, addlicense v1.2.0 for the
+# PowerShell files).
+RUN <<EOF
+set -o errexit -o nounset -o xtrace
+GOBIN=/usr/local/bin go install github.com/apache/skywalking-eyes/cmd/license-eye@v0.9.0
+GOBIN=/usr/local/bin go install github.com/google/addlicense@v1.2.0
+command -v license-eye addlicense
+EOF

.devcontainer/devcontainer.json

@@ -0,0 +1,19 @@
+{
+  "name": "vfox-java (Linux)",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": "."
+  },
+  "mounts": [
+    "source=${localEnv:DOCKER_SOCK:/var/run/docker.sock},target=/var/run/docker.sock,type=bind"
+  ],
+  "containerEnv": {
+    "TESTCONTAINERS_RYUK_DISABLED": "true"
+  },
+  "postCreateCommand": "cd tests/e2e && go mod download",
+  "customizations": {
+    "vscode": {
+      "extensions": ["golang.go", "sumneko.lua"]
+    }
+  }
+}

.dockerignore

@@ -0,0 +1,28 @@
+# Copyright 2026 Han Li and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# NOTE: tests/ is deliberately kept in the context: the Windows runner image
+# (tests/e2e/windows/Dockerfile-runner) is built from the repo root, and both
+# Windows Dockerfiles live under tests/.
+.git
+.gitignore
+.gitattributes
+.devcontainer
+.idea
+.github
+*.md
+docs
+LICENSE
+.tool-versions
+Injection.lua

.gitattributes

@@ -0,0 +1,18 @@
+# Copyright 2026 Han Li and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Keep every checkout LF: the Lua toolchain (stylua --check with
+# line_endings = "Unix") and the shell/Docker files are validated on Linux,
+# and Windows checkouts must not rewrite line endings.
+* text=auto eol=lf

.github/actionlint.yaml

@@ -0,0 +1,23 @@
+# Copyright 2026 Han Li and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# actionlint configuration (https://github.com/rhysd/actionlint).
+# The arm64 runner labels below are official GitHub-hosted labels
+# (see actions/runner-images), but actionlint's bundled label list lags
+# behind them; declaring them here keeps `actionlint` green for the E2E
+# workflow. GitHub itself ignores this file.
+self-hosted-runner:
+  labels:
+    - ubuntu-26.04-arm
+    - windows-11-arm

.github/workflows/e2e.yml

@@ -0,0 +1,97 @@
+# Copyright 2026 Han Li and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: E2E
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: e2e-${{ github.ref }}
+  cancel-in-progress: true
+
+# The Linux job runs the suite natively, the way the dev container runs it
+# locally: Go at the dev container's version (.devcontainer/Dockerfile) plus
+# the runner's stock Docker, with the same TESTCONTAINERS_RYUK_DISABLED knob.
+# The Windows jobs keep the compose runner image
+# (tests/e2e/windows/Dockerfile-runner), which carries its own Go toolchain,
+# so a Windows host needs only Docker. See docs/e2e.md.
+
+jobs:
+  e2e-linux:
+    if: github.repository == 'version-fox/vfox-java'
+    name: Linux container (${{ matrix.runs-on }})
+    strategy:
+      fail-fast: false
+      matrix:
+        runs-on: [ubuntu-latest, ubuntu-26.04-arm]
+    runs-on: ${{ matrix.runs-on }}
+    timeout-minutes: 60
+    env:
+      # Ryuk publishes a port on the host daemon and waits for the suite to
+      # dial back to it; the dev container disables it (it runs
+      # Docker-out-of-Docker), and CI matches so both paths stay identical.
+      # Containers are terminated explicitly via t.Cleanup instead.
+      TESTCONTAINERS_RYUK_DISABLED: "true"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-go@v6
+        with:
+          go-version: 1.27.1
+          cache: false
+      - run: go test -v -timeout 55m -run TestE2E ./linux
+        working-directory: tests/e2e
+
+  e2e-windows:
+    if: github.repository == 'version-fox/vfox-java'
+    name: Windows container (${{ matrix.runs-on }})
+    strategy:
+      fail-fast: false
+      matrix:
+        # TODO See https://github.com/actions/runner-images/issues/13729
+        runs-on: [windows-latest, windows-11-arm]
+        include:
+          - runs-on: windows-latest
+            compose: tests/e2e/windows/compose.amd64.yaml
+          - runs-on: windows-11-arm
+            compose: tests/e2e/windows/compose.arm64.yaml
+    runs-on: ${{ matrix.runs-on }}
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      # The windows-11-arm runner ships neither Docker for Windows containers
+      # nor a Go new enough to build moby, so both are provisioned here.
+      - if: matrix.runs-on == 'windows-11-arm'
+        uses: actions/setup-go@v6
+        with:
+          go-version: 1.27.1
+          cache: false
+      - if: matrix.runs-on == 'windows-11-arm'
+        run: pwsh -NoProfile -File tests/e2e/windows/install-docker-arm64.ps1
+      - if: matrix.runs-on == 'windows-11-arm'
+        name: Install Compose CLI plugin
+        run: |
+          New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.docker\cli-plugins" | Out-Null
+          curl.exe -fsSL "https://github.com/docker/compose/releases/download/v5.5.1/docker-compose-windows-aarch64.exe" -o "$env:USERPROFILE\.docker\cli-plugins\docker-compose.exe"
+          docker compose version
+      - run: docker compose -f ${{ matrix.compose }} run --rm --build e2e

.github/workflows/license.yml

@@ -0,0 +1,39 @@
+# Copyright 2026 Han Li and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: License
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  license-eye:
+    if: github.repository == 'version-fox/vfox-java'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - name: Check license headers
+        uses: apache/skywalking-eyes@v0.9.0
+        with:
+          config: .licenserc.yaml
+      - name: Check PowerShell license headers
+        run: docker run --rm -v "${{ github.workspace }}:/src" ghcr.io/google/addlicense:v1.2.0 -check -f .license.tpl tests/e2e/windows/*.ps1

.github/workflows/lint.yml

@@ -0,0 +1,62 @@
+# Copyright 2026 Han Li and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: Lint
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint-go:
+    if: github.repository == 'version-fox/vfox-java'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-go@v6
+        with:
+          go-version: '1.27.1'
+          cache: false
+      - name: Check gofmt
+        run: test -z "$(gofmt -l .)"
+        working-directory: tests/e2e
+      - name: Run go vet
+        run: go vet ./...
+        working-directory: tests/e2e
+      - name: Run unit tests
+        run: go test -short ./...
+        working-directory: tests/e2e
+
+  lint-lua:
+    if: github.repository == 'version-fox/vfox-java'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: jdx/mise-action@v5
+      - name: Check Lua formatting
+        uses: JohnnyMorganz/stylua-action@v5
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          version: v2.5.2
+          args: --check .
+      - name: Check Lua
+        run: mise x aqua:LuaLS/lua-language-server@3.19.1 -- lua-language-server --check . --checklevel=Warning

.github/workflows/publish.yaml

@@ -1,3 +1,17 @@
+# Copyright 2026 Han Li and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 name: Plugin
 
 on: