chore: align cross-platform dev environment with webware-tools

.devcontainer/devcontainer.json

@@ -0,0 +1,25 @@
+// Webware alignment Dev Container.
+//
+// This is a thin wrapper around compose.yml — it reuses the `tooling` service
+// rather than defining a parallel environment, so VS Code and plain
+// `docker compose` users share the exact same container. Non-VS Code
+// developers are not orphaned: they use `docker compose up -d` +
+// `docker compose exec tooling bash` directly.
+//
+// For format details, see https://aka.ms/devcontainer.json.
+{
+  "name": "Webware Tooling",
+  "dockerComposeFile": ["../compose.yml"],
+  "service": "tooling",
+  "workspaceFolder": "/app",
+  "shutdownAction": "none",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "bmewburn.vscode-intelephense-client",
+        "xdebug.php-debug",
+        "editorconfig.editorconfig"
+      ]
+    }
+  }
+}

.dockerignore

@@ -0,0 +1,16 @@
+# Exclude everything that doesn't belong in the build context. This keeps the
+# context sent to the Docker daemon small and avoids copying host-only or
+# generated artifacts into the image.
+.git
+.github
+.gitignore
+.gitattributes
+.vscode
+.devcontainer
+vendor
+.specify
+specs
+.phpunit.cache
+coverage
+node_modules
+*.log

Dockerfile

@@ -0,0 +1,99 @@
+# syntax=docker/dockerfile:1
+
+# ---------------------------------------------------------------------------
+# Webware alignment development environment image
+#
+# Builds a self-contained, interactive PHP development environment carrying
+# the Webware toolchain: PHP CLI, Composer, Mago, and Xdebug. Developers work
+# inside this container — either through the VS Code Dev Container (backed by
+# compose.yml) or by `docker compose up -d` + `docker compose exec tooling`.
+# The host machine (Windows, WSL, Linux, or macOS) never needs a native PHP
+# toolchain.
+#
+# All files in this repository are committed with LF line endings (see
+# .gitattributes), which keeps the container and host line endings consistent.
+# ---------------------------------------------------------------------------
+
+# PHP version to base the image on (latest 8.4 patch release). Keep in sync
+# with the package's supported PHP versions and `config.platform.php`.
+ARG PHP_VERSION=8.4.24
+
+# Composer version (copied from the official composer image at build time).
+ARG COMPOSER_VERSION=2
+
+# Named stage so Composer can be copied from it (--from does not support
+# inline variable expansion).
+FROM composer:${COMPOSER_VERSION} AS composer
+
+FROM php:${PHP_VERSION}-cli
+
+# Mago version to install. Keep in sync with the central `mago.toml`
+# `version =` pin in webware/webware-tools.
+ARG MAGO_VERSION=1.47.3
+
+# ---------------------------------------------------------------------------
+# System packages + PHP extensions
+# ---------------------------------------------------------------------------
+RUN set -eux; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends \
+        ca-certificates \
+        curl \
+        git \
+        libicu-dev \
+        libzip-dev \
+        unzip \
+    ; \
+    docker-php-ext-install -j"$(nproc)" \
+        intl \
+        pcntl \
+        zip \
+    ; \
+    pecl install pcov \
+    && docker-php-ext-enable pcov \
+    ; \
+    apt-get clean; \
+    rm -rf /var/lib/apt/lists/*
+
+# ---------------------------------------------------------------------------
+# Xdebug (step debugging)
+# ---------------------------------------------------------------------------
+# Installed but disabled by default (xdebug.mode=off) so it does not slow down
+# normal Composer/PHPUnit/Mago runs. Enable it with XDEBUG_MODE=debug (see
+# compose.yml) and connect the IDE to host.docker.internal.
+RUN set -eux; \
+    pecl install xdebug \
+    && docker-php-ext-enable xdebug \
+    ; \
+    { \
+        echo 'xdebug.mode=off'; \
+        echo 'xdebug.start_with_request=yes'; \
+        echo 'xdebug.client_host=host.docker.internal'; \
+    } >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
+
+# ---------------------------------------------------------------------------
+# Composer
+# ---------------------------------------------------------------------------
+COPY --from=composer /usr/bin/composer /usr/bin/composer
+
+# ---------------------------------------------------------------------------
+# Mago (statically linked Rust binary). Select the correct release asset for
+# the build target architecture so the same Dockerfile works on x86_64 and
+# arm64 hosts.
+# ---------------------------------------------------------------------------
+ARG TARGETARCH
+RUN set -eux; \
+    case "${TARGETARCH}" in \
+        amd64) MAGO_TRIPLE="x86_64-unknown-linux-gnu" ;; \
+        arm64) MAGO_TRIPLE="aarch64-unknown-linux-gnu" ;; \
+        *) echo "unsupported TARGETARCH: ${TARGETARCH}" >&2; exit 1 ;; \
+    esac; \
+    curl -fsSL \
+        "https://github.com/carthage-software/mago/releases/download/${MAGO_VERSION}/mago-${MAGO_VERSION}-${MAGO_TRIPLE}.tar.gz" \
+        -o /tmp/mago.tar.gz; \
+    tar -xzf /tmp/mago.tar.gz -C /tmp; \
+    install -m 0755 "/tmp/mago-${MAGO_VERSION}-${MAGO_TRIPLE}/mago" /usr/local/bin/mago; \
+    rm -rf /tmp/mago.tar.gz "/tmp/mago-${MAGO_VERSION}-${MAGO_TRIPLE}"; \
+    mago --version
+
+WORKDIR /app

compose.yml

@@ -0,0 +1,123 @@
+# ---------------------------------------------------------------------------
+# Webware alignment local development environment
+#
+# A persistent, interactive development environment that runs the full Webware
+# toolchain (Composer, PHPUnit, Mago, Infection, PHPBench, roave BC-check)
+# inside a container, so the host never needs a native PHP install. Works
+# identically on Windows, WSL, Linux, and macOS.
+#
+# This compose file is the single source of truth for the environment. Two
+# ways to use it:
+#
+#   1. VS Code Dev Container — "Reopen in Container" uses
+#      .devcontainer/devcontainer.json, which is *backed by* this file (it
+#      references the `tooling` service rather than defining its own).
+#
+#   2. Plain Docker Compose (any editor / no VS Code):
+#        docker compose up -d                 # start the persistent container
+#        docker compose exec tooling bash     # attach an interactive shell
+#        docker compose exec tooling composer install
+#        docker compose exec tooling composer test
+#        docker compose exec tooling mago lint
+#        docker compose down                  # stop it
+#
+# Packages whose tests need MySQL uncomment the `mysql` service below (and the
+# `phpmyadmin` web UI if wanted), plus the `depends_on` block on `tooling`. The
+# `mysql` service mirrors the `db-image` package parameter used by CI, and is
+# reachable from `tooling` as host `mysql` on port 3306 — matching the PhpDb
+# `mysql.local.php` connection convention. Packages that need a different
+# engine add an equivalent service here (postgres, mariadb, ...) mirroring
+# their own `db-image` parameter.
+# ---------------------------------------------------------------------------
+
+services:
+  tooling:
+    build:
+      context: .
+      args:
+        # PHP version to base the image on (latest 8.4 patch release). Keep
+        # in sync with the package's supported PHP versions and
+        # `config.platform.php`.
+        PHP_VERSION: "8.4.24"
+        # Keep in sync with the central mago.toml `version =` pin in
+        # webware/webware-tools.
+        MAGO_VERSION: "1.47.3"
+    # Keep the container alive so `docker compose exec` can attach to it.
+    # (VS Code Dev Containers override this with their own command.)
+    command: sleep infinity
+    stdin_open: true
+    tty: true
+    environment:
+      # Point Composer at the named volume so its cache and global config
+      # survive container rebuilds (and live on the fast Linux filesystem).
+      COMPOSER_HOME: /tmp/composer-cache
+      # Uncomment (or export in your shell) to enable step debugging:
+      # XDEBUG_MODE: debug
+    extra_hosts:
+      # Lets Xdebug connect back to the host IDE from Windows, macOS, or Linux
+      # (host-gateway resolves to the Docker host on every platform).
+      - "host.docker.internal:host-gateway"
+    volumes:
+      # Bind-mount the source so edits are visible on both the host and the
+      # container. vendor/ is deliberately overridden below with a named
+      # volume — do not bind-mount it from the host.
+      - .:/app
+      # Named volumes keep vendor/ and the Composer cache on the Linux
+      # filesystem. Bind-mounting vendor/ from a Windows host is extremely
+      # slow, so vendor/ is owned by the container and populated by
+      # `composer install` (it is gitignored anyway).
+      - vendor:/app/vendor
+      - composer-cache:/tmp/composer-cache
+    # Uncomment when the package's tests need MySQL (see the `mysql` service
+    # below). Ensures the database is ready before the shell attaches.
+    # depends_on:
+    #   mysql:
+    #     condition: service_healthy
+    working_dir: /app
+
+  # -------------------------------------------------------------------------
+  # MySQL (optional) — uncomment this whole block for packages whose tests
+  # need a MySQL database (e.g. webware-acl via php-db/phpdb-mysql).
+  #
+  # Mirror the spec's `db-image` / `db-env-json` / `db-port` Package Parameters
+  # so the dev database matches CI. Point the package's local DB config (e.g.
+  # config/autoload/mysql.local.php) at host `mysql`, port 3306, using the
+  # credentials below. Adjust MYSQL_DATABASE / MYSQL_USER / MYSQL_PASSWORD to
+  # the package's test-database convention.
+  # -------------------------------------------------------------------------
+  # mysql:
+  #   image: mysql:9.7
+  #   environment:
+  #     MYSQL_ROOT_PASSWORD: root
+  #     MYSQL_DATABASE: webware
+  #     MYSQL_USER: webware
+  #     MYSQL_PASSWORD: webware
+  #   healthcheck:
+  #     test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-uroot", "-proot"]
+  #     interval: 5s
+  #     timeout: 5s
+  #     retries: 30
+  #   volumes:
+  #     # Named volume keeps the data on the fast Linux filesystem and
+  #     # survives `docker compose down` (use `down -v` to wipe it).
+  #     - mysql-data:/var/lib/mysql
+  #
+  # # phpMyAdmin — optional web UI for the `mysql` service above. Reachable at
+  # # http://localhost:8080 (log in with the MYSQL_* credentials). Uncomment
+  # # alongside `mysql`.
+  # phpmyadmin:
+  #   image: phpmyadmin:latest
+  #   environment:
+  #     PMA_HOST: mysql
+  #     PMA_PORT: 3306
+  #   ports:
+  #     - "8080:80"
+  #   depends_on:
+  #     mysql:
+  #       condition: service_healthy
+
+volumes:
+  vendor:
+  composer-cache:
+  # Used by the optional `mysql` service above.
+  mysql-data: