feat: one-command Xdebug step-debugging (kiqr xdebug on/off)

[kjellbergzoey]

What

Adds kiqr xdebug on|off for one-command Xdebug step-debugging of theme/PHP code.

Why / approach

The official wordpress image ships without Xdebug, so it can't simply be enabled via an env var. Instead, when Xdebug is turned on, the wordpress service is built from a tiny generated Dockerfile that layers Xdebug onto the same php-pinned base image:

FROM wordpress:php8.3
RUN pecl install xdebug && docker-php-ext-enable xdebug
COPY xdebug.ini /usr/local/etc/php/conf.d/zz-xdebug.ini

The generated xdebug.ini runs in mode=debug, start_with_request=yes, and connects out to host.docker.internal:9003, with a matching extra_hosts: host.docker.internal:host-gateway added to the service so the container can reach the IDE on the host.

When Xdebug is off, the compose output is byte-for-byte identical to today (image:, single hostname extra_host). mariadb/wpcli/phpmyadmin are untouched.

Details

• src/lib/xdebug.ts (new, pure + unit-tested): buildXdebugDockerfile, xdebugIni, writeXdebugAssets, removeXdebugAssets.
• Config: xdebug?: boolean added to LocalConfig and the zod localConfigSchema. It's machine-local (debugging is a per-developer choice) and optional — absent means off, so existing configs keep working.
• RuntimeConfig gains xdebugEnabled; ComposeService.image is now optional and gains an optional build.
• up / restart read lc.xdebug, thread xdebugEnabled, and (re)generate or clean up the assets during the "Preparing site" step.
• kiqr xdebug <on|off> validates the arg (on/off) via zod, flips the local flag, writes/removes the assets, and prints a message to run kiqr restart to apply. It does not run Docker.

Applying it / IDE side

• Run kiqr restart (or the next kiqr up) to apply. The first start after enabling rebuilds the WordPress image, so it's slower once.
• Configure your IDE to listen on port 9003. In VS Code that's the PHP Debug extension's "Listen for Xdebug".

Not verified without Docker

There is no Docker daemon in this environment, so I could only unit-test the generators and the compose wiring. The following were NOT verified end-to-end:

• That pecl install xdebug && docker-php-ext-enable xdebug actually builds against every wordpress:php* base tag.
• That a real debugger connection is established from the container to the IDE on host.docker.internal:9003.

Only the pure generators (xdebug.ts), the config schema, and the provider's compose output are covered by tests.

Follow-ups

• Generating an IDE launch.json (VS Code "Listen for Xdebug") is a planned follow-up.
• README docs will follow in the separate README rewrite PR (not touched here).

🤖 Generated with Claude Code