CSS API: Add CSS token processor foundations

.env.example

@@ -18,6 +18,11 @@ LOCAL_DIR=src
 # Valid options are 'on' and 'off'.
 LOCAL_NGINX_COMPRESSION=off
 
+# How long browsers may cache static assets served by the web server, as an nginx `expires` value.
+# Valid options are 'off' and a duration such as '1y'. A far-future duration matches typical
+# production behavior, but edited CSS and JavaScript is then served stale until a hard reload.
+LOCAL_NGINX_STATIC_EXPIRES=off
+
 # The PHP version to use. Valid options are 'latest', and '{version}-fpm'.
 LOCAL_PHP=latest
 

.eslintrc-jsdoc.js

@@ -1,29 +1,88 @@
-module.exports = {
-	rules: {
-		'require-jsdoc': 'off',
-		'valid-jsdoc': [ 'error', {
-			prefer: {
-				arg: 'param',
-				argument: 'param',
-				extends: 'augments',
-				returns: 'return',
+/**
+ * ESLint v10 flat config file for JSDoc linting.
+ * This config is based on the original valid-jsdoc rules.
+ */
+
+const jsdocPlugin = require( 'eslint-plugin-jsdoc' );
+
+module.exports = [
+	{
+		plugins: {
+			jsdoc: jsdocPlugin,
+		},
+		settings: {
+			jsdoc: {
+				tagNamePreference: {
+					'arg': 'param',
+					'argument': 'param',
+					'extends': 'augments',
+					'returns': 'return',
+				},
+				preferredTypes: {
+					'array': 'Array',
+					'bool': 'boolean',
+					'Boolean': 'boolean',
+					'float': 'number',
+					'Float': 'number',
+					'function': 'Function',
+					'int': 'number',
+					'integer': 'number',
+					'Integer': 'number',
+					'Number': 'number',
+					'object': 'Object',
+					'String': 'string',
+					'Void': 'void',
+				},
 			},
-			preferType: {
-				array: 'Array',
-				bool: 'boolean',
-				Boolean: 'boolean',
-				float: 'number',
-				Float: 'number',
-				int: 'number',
-				integer: 'number',
-				Integer: 'number',
-				Number: 'number',
-				object: 'Object',
-				String: 'string',
-				Void: 'void',
-			},
-			requireParamDescription: false,
-			requireReturn: false,
-		} ],
+		},
+		rules: {
+			'jsdoc/check-alignment': 'error',
+			'jsdoc/check-indentation': [ 'error', {
+				excludeTags: [
+					'deprecated',
+					'example',
+					'param',
+					'property',
+					'return',
+					'since',
+					'todo',
+				],
+			} ],
+			'jsdoc/check-line-alignment': [ 'error', 'always', {
+				tags: [ 'param', 'property' ],
+			} ],
+			'jsdoc/check-param-names': 'error',
+			'jsdoc/check-property-names': 'error',
+			'jsdoc/check-syntax': 'error',
+			'jsdoc/check-tag-names': [ 'error', {
+				definedTags: [
+					'memberOf',
+					'output',
+					'ticket',
+					'link',
+				],
+			} ],
+			'jsdoc/check-types': 'error',
+			'jsdoc/no-blank-blocks': 'error',
+			'jsdoc/no-blank-block-descriptions': 'error',
+			'jsdoc/require-description': 'error',
+			'jsdoc/require-hyphen-before-param-description': [ 'error', 'never' ],
+			'jsdoc/require-jsdoc': 'error',
+			'jsdoc/require-param': [ 'error', {
+				enableFixer: false,
+			} ],
+			'jsdoc/require-param-description': 'error',
+			'jsdoc/require-param-name': 'error',
+			'jsdoc/require-param-type': 'error',
+			'jsdoc/require-property': 'error',
+			'jsdoc/require-property-name': 'error',
+			'jsdoc/require-property-description': 'error',
+			'jsdoc/require-property-type': 'error',
+			'jsdoc/require-returns': 'error',
+			'jsdoc/require-returns-check': 'error',
+			'jsdoc/require-returns-description': 'error',
+			'jsdoc/require-returns-type': 'error',
+			'jsdoc/valid-types': 'error',
+		},
 	},
-};
+];

.github/actions/setup-npm/action.yml

@@ -0,0 +1,55 @@
+name: 'Set up npm'
+description: 'Installs the npm version required by the devEngines field of package.json, so every job resolves dependencies identically. Keeps the bundled npm when the field is absent.'
+
+inputs:
+  working-directory:
+    description: 'Optional. The directory holding the package.json to read the required npm version from. Defaults to the workspace root.'
+    required: false
+    default: '.'
+  cache:
+    description: 'Optional. Whether to restore and save the npm cache. Defaults to true.'
+    required: false
+    default: 'true'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Install npm
+      id: npm
+      env:
+        WORKING_DIRECTORY: ${{ inputs.working-directory }}
+      run: |
+        NPM_VERSION="$(jq -r '.devEngines.packageManager.version // empty' package.json)"
+        if [ -n "$NPM_VERSION" ]; then
+          # Contributors need the floor; CI stays on that major's newest release.
+          npm install --global "npm@${NPM_VERSION/>=/^}"
+          echo "Required npm version: $NPM_VERSION"
+        else
+          echo "No devEngines.packageManager.version, keeping the bundled npm."
+        fi
+        echo "Installed npm version: $(npm --version)"
+
+        # actions/setup-node cannot restore the npm cache: it locates the
+        # directory with `npm config get cache`, which runs before this step
+        # and fails the devEngines check under the bundled npm.
+        echo "cache-dir=$(npm config get cache | tr -d '\r')" >> "$GITHUB_OUTPUT"
+
+        # Scopes the cache key to this package and keeps the hashFiles patterns
+        # workspace-relative and free of a "./" prefix, so they match the same
+        # files as every other cache key.
+        PATH_PREFIX=""
+        if [ "$WORKING_DIRECTORY" != '.' ] && [ -n "$WORKING_DIRECTORY" ]; then
+          PATH_PREFIX="${WORKING_DIRECTORY%/}/"
+        fi
+        echo "path-prefix=$PATH_PREFIX" >> "$GITHUB_OUTPUT"
+      working-directory: ${{ inputs.working-directory }}
+      shell: bash
+
+    - name: Cache npm downloads
+      if: ${{ inputs.cache == 'true' }}
+      uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+      with:
+        path: ${{ steps.npm.outputs.cache-dir }}
+        key: npm-cache-${{ runner.os }}-${{ runner.arch }}-${{ steps.npm.outputs.path-prefix }}lock-${{ hashFiles(format('{0}package-lock.json', steps.npm.outputs.path-prefix), format('{0}patches/**', steps.npm.outputs.path-prefix)) }}
+        restore-keys: |
+          npm-cache-${{ runner.os }}-${{ runner.arch }}-${{ steps.npm.outputs.path-prefix }}lock-

.github/actions/smoke-check/action.yml

@@ -0,0 +1,20 @@
+name: 'Smoke check a WordPress installation'
+description: 'Serves an installed single site with PHP built-in web server and checks that its front end, REST API, and admin respond.'
+
+inputs:
+  admin-user:
+    description: 'The username of an administrator account on the site.'
+    required: true
+  admin-password:
+    description: 'The password of the administrator account.'
+    required: true
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Serve the site and check it
+      shell: bash
+      run: bash "${GITHUB_ACTION_PATH}/smoke-check.sh"
+      env:
+        WP_ADMIN_USER: ${{ inputs.admin-user }}
+        WP_ADMIN_PASSWORD: ${{ inputs.admin-password }}

.github/actions/smoke-check/smoke-check.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+#
+# Smoke checks an installed WordPress single site over HTTP.
+#
+# Runs from the root of the installation, with WP-CLI available. Multisite is not supported because
+# a network's domain lives in wp-config.php and the database, not just an option.
+
+set -euo pipefail
+
+: "${RUNNER_TEMP:?}" "${WP_ADMIN_USER:?}" "${WP_ADMIN_PASSWORD:?}"
+
+site_port=8889
+site_url="http://127.0.0.1:${site_port}"
+server_log="${RUNNER_TEMP}/server.log"
+jar="${RUNNER_TEMP}/cookies.txt"
+: > "${jar}"
+response="${RUNNER_TEMP}/response.txt"
+code="${RUNNER_TEMP}/http-code.txt"
+http_code=''
+
+version="$(wp core version)"
+
+# Nothing undoes these, so the site is only good for this check afterwards.
+wp option update home "${site_url}"
+wp option update siteurl "${site_url}"
+# A fresh install shows posts here already, but the front page check below needs it.
+wp option update show_on_front posts
+# Both make requests no check asked for, and the update checks call api.wordpress.org.
+wp config set DISABLE_WP_CRON true --raw
+wp config set WP_HTTP_BLOCK_EXTERNAL true --raw
+
+# opcache counts php -S as a web SAPI, so the runner's JIT runs here and segfaults.
+php -d opcache.jit=disable -S "127.0.0.1:${site_port}" -t . > "${server_log}" 2>&1 &
+server_pid=$!
+
+stop_server() {
+  local status=$?
+  kill "${server_pid}" 2> /dev/null || true
+  wait "${server_pid}" 2> /dev/null || true
+  [ "${status}" -eq 0 ] || cat "${server_log}" || true
+  exit "${status}"
+}
+trap stop_server EXIT
+
+# No connection prints 000 and exits 7, which set -e would take as fatal.
+deadline=$(( SECONDS + 30 ))
+while :; do
+  ready_code="$(curl --silent --max-time 5 --output /dev/null --write-out '%{http_code}' "${site_url}/" || true)"
+  [ "${ready_code}" = '000' ] || break
+  [ "${SECONDS}" -lt "${deadline}" ] || { echo '::error::the server never answered'; exit 1; }
+  sleep 1
+done
+
+fail() {
+  echo "::error::${1}"
+  tail -n 20 "${response}"
+  exit 1
+}
+
+# An HTTP error returns to the caller. No reply at all is fatal.
+fetch() {
+  local path="${1}" status=0
+  shift
+  : > "${response}"
+  curl --silent --show-error --max-time 30 --output "${response}" \
+    --write-out '%{http_code}' --cookie "${jar}" --cookie-jar "${jar}" \
+    "$@" "${site_url}${path}" > "${code}" || status=$?
+  http_code="$(cat "${code}")"
+  [ "${status}" -eq 0 ] || [ "${status}" -eq 22 ] \
+    || fail "${path} got no reply and curl exited ${status}"
+  return "${status}"
+}
+
+check() {
+  local path="${1}" marker status=0
+  shift
+  fetch "${path}" --fail-with-body || status=$?
+  [ "${status}" -eq 0 ] || fail "${path} returned HTTP ${http_code}"
+  for marker in "$@"; do
+    grep -qF -e "${marker}" "${response}" || fail "${path} did not contain: ${marker}"
+  done
+  echo "ok  ${path}"
+}
+
+# A fatal mid-page still returns 200, so every check also asks for the closing tag.
+check '/' "content=\"WordPress ${version}\"" 'Hello world!' '</html>'
+
+fetch '/?rest_route=/' --fail-with-body || fail "/?rest_route=/ returned HTTP ${http_code}"
+jq -e --arg url "${site_url}" '.url == $url and ( .namespaces | index( "wp/v2" ) )' "${response}" > /dev/null \
+  || fail 'the REST index was not the expected JSON'
+echo 'ok  /?rest_route=/'
+
+# It prints this for an empty database too, which the checks above rule out.
+check '/wp-admin/upgrade.php' 'No Update Required' '</html>'
+
+fetch '/?p=99999999' || true
+[ "${http_code}" = '404' ] || fail "a missing post returned ${http_code}, expected 404"
+grep -qF '</html>' "${response}" || fail 'the 404 page was cut short'
+echo 'ok  404 handling'
+
+login_status=0
+fetch '/wp-login.php' --fail-with-body \
+  --data-urlencode "log=${WP_ADMIN_USER}" --data-urlencode "pwd=${WP_ADMIN_PASSWORD}" || login_status=$?
+[ "${login_status}" -eq 0 ] || fail "logging in returned HTTP ${http_code}"
+grep -qF 'wordpress_logged_in_' "${jar}" || fail 'logging in did not set an authentication cookie'
+echo 'ok  login'
+
+# The admin bar renders only for a logged-in user.
+check '/wp-admin/' 'id="wpadminbar"' '</html>'
+
+# Catches a fatal during shutdown. An empty log would let the grep pass silently.
+[ -s "${server_log}" ] || { echo '::error::the server wrote no log'; exit 1; }
+if grep -qE 'Fatal error|Uncaught|Segmentation fault' "${server_log}"; then
+  echo '::error::the server logged a fatal error'
+  exit 1
+fi
+echo 'ok  server log'