From 7c9480c70e79c183ff5104cadef0981b53383e4e Mon Sep 17 00:00:00 2001 From: David Stone Date: Sun, 26 Apr 2026 05:26:28 -0600 Subject: [PATCH 1/2] GH#951: add bin/check-env.sh and update AGENTS.md Quick Session Checklist Adds a runnable bash script that checks all development prerequisites in one pass (PHP, composer, npm, wp-cli, WordPress dev env, WP test suite, xdebug) and prints actionable fix instructions for anything missing. Updates AGENTS.md Quick Session Checklist item 4 to surface this script as the first thing to run, consolidating the individual inline checks that were scattered across the section. Rationale: five documentation-only PRs (#920, #929, #933, #944, #949) have already strengthened the written guidance for the four recurring error patterns in issue #951. The remaining gap for bash:other is converting the prerequisite check from prose instructions into a runnable script that exits 1 on failure, so agents can detect missing tools without reading multiple documentation sections. Resolves #951 --- AGENTS.md | 4 ++- bin/check-env.sh | 87 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 90 insertions(+), 1 deletion(-) create mode 100755 bin/check-env.sh diff --git a/AGENTS.md b/AGENTS.md index 9fd3c551..55111a1c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -199,7 +199,9 @@ Recurring error patterns observed in this codebase. Review before starting any s same conversation turn on that exact file. `Read(A) → Edit(A)` is correct. `Read(A) → Read(B) → Edit(A)` fails if A's content changed, and will always fail on session restart. Never read multiple files upfront and edit them later. -4. **Check tool prerequisites** — before any lint, test, or analysis command, confirm: +4. **Check tool prerequisites** — run `bash bin/check-env.sh` for a single pass that checks + all prerequisites (vendor, node_modules, wp-cli, WordPress dev env, WP test suite) and + prints exactly what's missing with fix instructions. Or check individually: - `ls vendor/autoload.php 2>/dev/null || echo "run: composer install"` - `ls node_modules/.bin/eslint 2>/dev/null || echo "run: npm install"` - `ls /tmp/wordpress-tests-lib/includes/bootstrap.php 2>/dev/null || echo "run: bin/install-wp-tests.sh"` diff --git a/bin/check-env.sh b/bin/check-env.sh new file mode 100755 index 00000000..345799f5 --- /dev/null +++ b/bin/check-env.sh @@ -0,0 +1,87 @@ +#!/bin/bash + +# check-env.sh — Verify all development prerequisites before running tests, lint, or WP-CLI. +# +# Run this before any lint, test, or WP-CLI command to catch missing tools early +# and avoid bash:other failures. Exit codes: 0=all OK, 1=one or more checks failed. + +set -euo pipefail + +any_fail=0 + +ok() { echo "[OK] $1"; } +fail() { + echo "[!!] $1" + any_fail=1 +} +info() { echo " $1"; } +note() { echo "[--] $1"; } + +echo "=== Development environment check ===" +echo "" + +# 1. PHP binary +if command -v php >/dev/null 2>&1; then + ok "PHP found: $(php -r 'echo PHP_VERSION;' 2>/dev/null || echo "(version unknown)")" +else + fail "PHP not in PATH — install PHP 7.4+ and ensure it is on PATH" +fi + +# 2. Composer vendor directory +if [ -f "vendor/autoload.php" ]; then + ok "composer install — vendor/autoload.php found" +else + fail "composer install not run — vendor/autoload.php missing" + info "Fix: composer install" +fi + +# 3. Node modules +if [ -f "node_modules/.bin/eslint" ]; then + ok "npm install — node_modules/.bin/eslint found" +else + fail "npm install not run — node_modules/.bin/eslint missing" + info "Fix: npm install" +fi + +# 4. WP-CLI +if command -v wp >/dev/null 2>&1; then + ok "wp-cli found: $(wp --version --allow-root 2>/dev/null || echo "(version unknown)")" +else + fail "wp-cli not in PATH" + info "Install: https://wp-cli.org/#installing (download wp-cli.phar and add to PATH)" +fi + +# 5. WordPress dev install +if [ -f "../wordpress/wp-config.php" ]; then + ok "WordPress dev install found at ../wordpress" +else + fail "WordPress dev install missing at ../wordpress" + info "Fix: cd ../wordpress && ./reset.sh (or clone the dev WP install there)" +fi + +# 6. WP test suite +WP_TESTS_DIR="${WP_TESTS_DIR:-/tmp/wordpress-tests-lib}" +if [ -f "${WP_TESTS_DIR}/includes/bootstrap.php" ]; then + ok "WP test suite found at ${WP_TESTS_DIR}" +else + fail "WP test suite not installed at ${WP_TESTS_DIR}" + info "Fix: bash bin/install-wp-tests.sh [db-host]" + info " Example: bash bin/install-wp-tests.sh wordpress_test root root localhost" +fi + +# 7. xdebug (optional — only needed for coverage reports) +if php -m 2>/dev/null | grep -qi xdebug; then + note "xdebug loaded — coverage reports supported" +else + note "xdebug NOT loaded (optional) — coverage flags will fail; unit tests run fine" + info "Omit coverage flags: use vendor/bin/phpunit (not php -d zend_extension=xdebug ...)" +fi + +echo "" +if [ "$any_fail" -eq 0 ]; then + echo "All checks passed. Environment ready." + exit 0 +else + echo "One or more checks failed. Fix the items marked [!!] above before running tests or lint." + exit 1 +fi From 23912178b80cda5fd13c1b88c9decbff91f9e9e1 Mon Sep 17 00:00:00 2001 From: David Stone Date: Sun, 26 Apr 2026 05:39:00 -0600 Subject: [PATCH 2/2] fix(check-env): add CWD guard so script always runs from repo root Addresses CodeRabbit review: path-based checks (vendor/, node_modules/, ../wordpress/) are relative to CWD, which caused spurious failures if the script was invoked from a subdirectory or editor task with a non-root CWD. The guard computes the repo root from the script's own location and cd's to it before performing any checks, so the output is always correct regardless of where the caller's working directory was. --- bin/check-env.sh | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/bin/check-env.sh b/bin/check-env.sh index 345799f5..05ec546d 100755 --- a/bin/check-env.sh +++ b/bin/check-env.sh @@ -7,6 +7,10 @@ set -euo pipefail +# Always run from the repo root regardless of where the script was invoked. +SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)" +cd -- "${SCRIPT_DIR}/.." + any_fail=0 ok() { echo "[OK] $1"; }