build: stabilize the wp-env utilities

[dcalhoun]

What?

Three failure modes in the wp-env make targets: credentials went stale after every restart, a mistimed start could orphan the Playground server and wedge the environment, and the Android URL targets triggered that orphan by design.

Why?

make wp-env-start produced an environment the demo apps couldn't authenticate against, and recovering from a wedged server meant running lsof and kill by hand.

Stale credentials. The Playground runtime has no persistent database. Every start replays the Blueprint into a fresh database, recreating the admin user and discarding its application password. The credentials file is the one artifact that survives — so skipping setup when that file exists guaranteed stale credentials after any stop/start.

Orphaned server. Starting a second server fails with EADDRINUSE, and wp-env unlinks the PID file as it unwinds — including when that file names the healthy server still running. wp-env stop and wp-env status trust the PID file alone, so afterwards they report ✔ Stopped and status: stopped while the server keeps serving.

Android targets. wp-env-android and wp-env-android-reset called wp-env-start with no stop first, which is exactly the double-start above. The restart was never needed: mu-plugins are mounted into the running server, so the toggle applies on the next request.

How?

Credentials — probe /wp/v2/users/me with the stored auth header; reuse on a clean 200, regenerate otherwise. This removes RESET, which existed only to force the regeneration the probe now handles.

Guard — check the port before starting (bin/wp-env-guard.sh). Ours running → skip the start, verify credentials. Untracked process → report the PIDs, their command lines, and the command that stops them, then exit.

It reports rather than stopping anything itself. Each worktree tracks its own environment while sharing one port, so a process holding it may be another worktree's healthy site; telling them apart needs a person, and stopping the wrong one interrupts work elsewhere.

The port and work directory come from wp-env's own config loader, so WP_ENV_HOME, WP_ENV_PORT, and a port key in .wp-env.json are all honoured. bin/wp-env-setup.sh resolves the port the same way, so provisioning follows the site when it moves.

Android — one wp-env-android-urls target taking MODE=on|off. No restart, so content and credentials survive. With no MODE it reports the current setting and suggests the flag to change it. Docs move off the images-only framing, since block editor assets, theme styles, and REST links all remap too.

Clean — wp-env destroy stops only the server named by its PID file, so it can report success while a server keeps holding the port. wp-env-clean runs the same check afterwards and reports anything still listening, so the next start does not fail on it.

Testing Instructions

1. make wp-env-start — environment starts, credentials provisioned.
2. make wp-env-start again — reports "already running" and finishes in seconds, noting that applying .wp-env.json changes needs a stop first. (Previously: EADDRINUSE, orphaned server.)
3. make wp-env-stop, then make wp-env-start. Open http://localhost:8888/wp-admin/ and confirm the editor loads. In the iOS or Android demo app, open Local WordPress and confirm it connects. (Previously: failed to authenticate.)
4. make wp-env-android-urls — reports off and suggests MODE=on.
5. make wp-env-android-urls MODE=on — returns immediately, no restart. Rebuild the Android app, open Local WordPress in the emulator, and confirm images and block assets load.
6. make wp-env-android-urls MODE=off — reverts; http://localhost:8888/wp-admin/ loads in a browser again.

Accessibility Testing Instructions

N/A — developer tooling, no UI changes.

[wpmobilebot]

XCFramework Build

This PR's XCFramework is available for testing. Add the following to your Package.swift:

.package(url: "https://github.com/wordpress-mobile/GutenbergKit", branch: "pr-build/597")

_{Built from c6c82d5}

[dcalhoun]

Added to address a deprecation warning:

⚠ Warning: wp-env starts both development and tests environments by default.
This behavior is deprecated and will be removed in a future version.
To avoid this warning, add "testsEnvironment": false to your .wp-env.json.
The "env", "testsPort", and "testsEnvironment" options are also deprecated.
Use the --config option with a separate config file for test environments instead.