wp-env: Update JSON Schema with missing properties and add README docs

AGENTS.md

@@ -19,6 +19,7 @@ npm run build          # Production build
 -   `/lib/` - PHP code
 -   `/lib/compat/wordpress-X.Y/` - Version-specific features (new PHP features usually go here)
 -   `/phpunit/` - PHP tests
+-   `/schemas/json/` - JSON Schemas for `block.json`, `theme.json`, `font-collection.json`, and `wp-env.json` (published to `schemas.wp.org`; tests in `/test/integration/`)
 -   `/docs/` - Documentation
     -   `/docs/contributors/` - Contributing guides
     -   `/docs/explanations/architecture/` - System architecture docs

packages/env/README.md

@@ -586,6 +586,15 @@ Options:
 
 You can customize the WordPress installation, plugins and themes that the development environment will use by specifying a `.wp-env.json` file in the directory that you run `wp-env` from.
 
+To enable editor autocomplete and validation, add a `$schema` key:
+
+```json
+{
+	"$schema": "https://schemas.wp.org/trunk/wp-env.json",
+	"plugins": [ "." ]
+}
+```
+
 `.wp-env.json` supports the following fields:
 
 | Field                | Type           | Default                                | Description                                                                                                                      |

schemas/README.md

@@ -1,6 +1,6 @@
 # Schemas
 
-The collection of schemas used in WordPress, including the `theme.json`, `block.json` and `font-collection.json` schemas.
+The collection of schemas used in WordPress, including the `theme.json`, `block.json`, `font-collection.json`, and `wp-env.json` schemas.
 
 JSON schemas are used by code editors to offer tooltips, autocomplete, and validation.
 
@@ -32,6 +32,14 @@ Or in your `font-collection.json`:
 }
 ```
 
+Or in your `.wp-env.json`:
+
+```json
+{
+	"$schema": "https://schemas.wp.org/trunk/wp-env.json"
+}
+```
+
 For a specific version of the schema, replace `trunk` with `wp/X.X`:
 
 ```json

schemas/json/wp-env.json

@@ -24,7 +24,8 @@
 					"description": "The PHP version to use. If null is specified, wp-env will use the default version used with production release of WordPress.",
 					"oneOf": [
 						{
-							"type": "string"
+							"type": "string",
+							"pattern": "^[0-9]+\\.[0-9]+$"
 						},
 						{
 							"type": "null"
@@ -51,16 +52,37 @@
 				"port": {
 					"description": "The primary port number to use for the installation. You'll access the instance through the port: http://localhost:8888",
 					"type": "integer",
+					"minimum": 1,
+					"maximum": 65535,
 					"default": 8888
 				},
+				"mysqlPort": {
+					"description": "The port number for the MySQL database. If null, the port is not exposed.",
+					"oneOf": [
+						{
+							"type": "integer",
+							"minimum": 1,
+							"maximum": 65535
+						},
+						{
+							"type": "null"
+						}
+					]
+				},
 				"config": {
 					"description": "Mapping of wp-config.php constants to their desired values.",
 					"type": "object",
+					"additionalProperties": {
+						"type": [ "string", "number", "boolean" ]
+					},
 					"default": {}
 				},
 				"mappings": {
 					"description": "Mapping of WordPress directories to local directories to be mounted in the WordPress instance.",
 					"type": "object",
+					"additionalProperties": {
+						"type": "string"
+					},
 					"default": {}
 				},
 				"phpmyadmin": {
@@ -70,7 +92,16 @@
 				},
 				"phpmyadminPort": {
 					"description": "The port number to access phpMyAdmin. Setting this also enables phpMyAdmin.",
-					"type": "integer"
+					"oneOf": [
+						{
+							"type": "integer",
+							"minimum": 1,
+							"maximum": 65535
+						},
+						{
+							"type": "null"
+						}
+					]
 				},
 				"multisite": {
 					"description": "Whether to set up a multisite installation.",
@@ -85,6 +116,7 @@
 				"plugins",
 				"themes",
 				"port",
+				"mysqlPort",
 				"config",
 				"mappings",
 				"phpmyadmin",
@@ -124,13 +156,20 @@
 				"testsPort": {
 					"description": "The port number for the test site. You'll access the instance through the port: http://localhost:8889",
 					"type": "integer",
+					"minimum": 1,
+					"maximum": 65535,
 					"default": 8889
 				},
 				"testsEnvironment": {
 					"description": "Whether to create the tests environment. Set to false to skip creating test containers, saving resources.",
 					"type": "boolean",
 					"default": true
 				},
+				"autoPort": {
+					"description": "Whether to automatically find available HTTP ports when configured ports are busy.",
+					"type": "boolean",
+					"default": false
+				},
 				"lifecycleScripts": {
 					"description": "Mapping of commands that should be executed at certain points in the lifecycle.",
 					"type": "object",
@@ -144,6 +183,14 @@
 							"description": "Runs after wp-env clean has finished cleaning the environment.",
 							"type": "string"
 						},
+						"afterReset": {
+							"description": "Runs after wp-env reset has finished resetting the environment.",
+							"type": "string"
+						},
+						"afterCleanup": {
+							"description": "Runs after wp-env cleanup has finished cleaning up the environment.",
+							"type": "string"
+						},
 						"afterDestroy": {
 							"description": "Runs after wp-env destroy has destroyed the environment.",
 							"type": "string"
@@ -165,6 +212,7 @@
 							"env",
 							"testsPort",
 							"testsEnvironment",
+							"autoPort",
 							"lifecycleScripts"
 						]
 					}