Site Health: Porta recommended settings check-list (extensible registry, hybrid effect/config verification)

[parisek]

Tracking / design issue — capturing the idea + decisions so far. To be picked
up later. Related to #40 (the hardening this board would verify).

Motivation

Our recommended project settings (security hardening, caching, SEO, performance,
mail deliverability, accessibility) are spread across plugin checkboxes whose
state lives in the DB, not in git. The recurring pain: it's hard to find out
retroactively "what click is set where" on a given site. There's no single place
that says "here is what Porta recommends, and here is what is actually active
right now on this install."

Idea: a TimberKit-provided health check-list surfaced in WordPress Site Health
(Tools → Site Health), which lists our recommended settings and verifies the real,
effective state — so auditing a site is one screen, not archaeology through plugin
admin pages.

Why Site Health (native site_status_tests API):

• Built-in UI with good / recommended / critical statuses + per-test
  description and "Actions" link.
• Supports async (REST-backed) tests for checks that do real probes.
• Editors/admins already know where it lives; no custom admin page to maintain.

Decisions already made (from design discussion)

1. Scope: full "Porta recommended" board, not security-only — security,
   caching, SEO, performance, mail deliverability, accessibility. But built as an
   extensible check registry, security checks first, other categories added
   incrementally. One cohesive subsystem (registry + Site Health adapter), many
   checks — no need to split into separate features.

2. Verification model: hybrid — each check declares its own method. The core
   supports all three; every check picks what fits:

   • effect — probe the real outcome, plugin-agnostic. Preferred where possible
     because it survives plugin swaps (e.g. the Add dev media proxy #2 NinjaFirewall → AIOS
     consolidation) and checks results, not a specific vendor's checkbox.
     Examples: does /wp-json/wp/v2/users return data to an anonymous request?
     is get_the_generator('xhtml') empty? did the response carry HSTS?
     does apply_filters('xmlrpc_enabled', true) return false?
   • config — read a specific plugin's stored option when there's no observable
     effect (e.g. NinjaFirewall nfw_options[enum_restapi], Breeze settings,
     SMTP host configured). Thin per-plugin adapter, used only as needed.
   • both — cross-check effect against config to catch "checkbox on but not
     actually working" (cache layer, edge proxy, etc.).

   This directly dissolves the core pain: for effect checks you stop caring
   which click produced the result — you verify the result itself.

Proposed architecture (to refine when implemented)

• HealthCheck — a small value object / interface each check implements:
  • id, label, category (security|caching|seo|performance|mail|a11y)
  • recommendation (what Porta recommends + why)
  • method (effect | config | both)
  • run(): Result returning good|recommended|critical + a human message +
    optional remediation hint / link
• CheckRegistry — collects checks, lets projects add/override/disable per
  site (a child class or filter — consistent with the existing protected bool
  override pattern in StarterBase).
• SiteHealthAdapter — maps registered checks onto site_status_tests
  (sync where cheap, async REST for real probes). The ONLY coupling to WP Site
  Health; the registry + checks stay framework-agnostic and unit-testable.
• (optional later) a compact "Porta status" summary widget that aggregates the
  board into one pass/fail count.

Per the design-for-isolation principle: checks are independent units (one purpose,
own run()), the adapter is the only Site Health touchpoint, the registry is the
only wiring — each testable in isolation.

Starter checks per category (seed list, not exhaustive)

• Security (mirrors Security hardening: info-disclosure gaps vs WAF layer + optional security-headers emitter #40): WP version hidden (the_generator empty); REST users
  endpoint restricted for anon; ?author=N + author sitemap blocked; XML-RPC off;
  Application Passwords off; DISALLOW_FILE_EDIT; 6 response headers present
  (incl. HSTS proxy-safe); wp-login not enumerable.
• Caching: a page-cache plugin active (Breeze/Rocket/…); object cache present;
  expected Cache-Control / cache-provider header observed.
• SEO: exactly one SEO plugin active (no Yoast+AIOSEO overlap — see Add dev media proxy #2);
  sitemap reachable; robots.txt not blocking; canonical/meta present on a probe.
• Performance: PHP version >= target; gzip/deflate on; images served as
  WebP/AVIF; no obvious render-block flagged.
• Mail deliverability: an SMTP/mailer plugin configured (host set); SPF/DKIM
  hint (config-level, can't fully verify from PHP).
• Accessibility: lightweight static hints (lang attribute, skip-link, alt
  coverage sample) — clearly "advisory", not a full audit.

Non-goals

• Not a replacement for a real WAF, a real Lighthouse/a11y audit, or external
  deliverability testing — these checks are configuration-presence + effect
  smoke checks, deliberately cheap.
• No heavy per-request work; probes run inside Site Health (on demand), never on
  front-end page loads.

Open questions (resolve at implementation time)

• Sync vs async split — which checks justify the async REST test?
• How do projects opt a check out / change its severity (filter vs subclass)?
• Do we ship a CLI (wp porta:health) mirror for CI/headless, or Site-Health-only?
• Per-plugin config adapters: ship NinjaFirewall + Breeze first; how to keep them
  optional so the package has zero hard plugin dependency?

Acceptance (high level)

• HealthCheck interface + Result type
• CheckRegistry with per-project add/override/disable
• SiteHealthAdapter registering checks via site_status_tests
• Security category seeded (verifies Security hardening: info-disclosure gaps vs WAF layer + optional security-headers emitter #40 hardening)
• Hybrid effect/config/both supported with at least one of each
• Docs: category list + how to add a check + how to override per project

[parisek]

Design refinement — code-first configuration, timber-kit category, CLI mirror

Follow-up design session (2026-07-11). Everything below sharpens the existing plan; no reversals.

Guiding principle: Site Health only reads, git is the source of truth

The board is a read-only dashboard. No options page, no DB-stored toggles, no remediation buttons. The definition of "what is correct" lives in versioned code:

• timber-kit ships the default check set (versioned in the package, propagates via composer bump),
• projects adjust the set exclusively in code — Base.php override first, filter second (see below).

This turns the original pain around: the expected state becomes codified in the repo for the first time, and Site Health merely reports drift between git and reality. The "Actions" link on a test points to remediation docs ("fix it in code like this"), never to an admin screen.

Conscious exceptions: Base.php override as the primary path

Primary mechanism is a protected method on StarterBase, consistent with the kit's existing flag/override pattern. The filter stays underneath as the uniform low-level hook (plugins, mu-plugins, per-environment tweaks):

// StarterBase (kit)
protected bool $site_health = false;   // opt-in flag, default false in 1.x

protected function health_checks( array $checks ): array {
    return $checks;                     // projects override this
}

// Base.php of a project — a conscious exception, visible in the PR diff
protected function health_checks( array $checks ): array {
    unset( $checks['hsts'] );           // behind edge proxy, HSTS handled there — see PD-123
    $checks['custom_probe'] = new MyCheck();
    return $checks;
}

Order matters: the kit calls $this->health_checks() first, then passes the result through apply_filters( 'timber_kit_health_checks', ... ) (underscore convention per #66). Convention: every exception carries a comment explaining why — enforced by review, visible in history.

This also pre-answers the #66 question about the fate of private registerXxxHooks() methods: a new feature ships with its supported override surface (protected, documented) from day one.

New category: timber-kit (self-diagnostics)

Beyond the original six categories, add checks the June 2026 fleet audit (#66) showed we need:

• kit version currency — installed version vs. latest release (Packagist API, cached in a transient). Attacks "21/22 installs lag behind".
• deprecated API usage — project calls Helpers::resizeImage() or sets $max_upload_width? Warning with the replacement. Prepares projects for the 2.0 removals before the bump lands.
• flag inventory — effective values of all StarterBase properties vs. defaults, surfaced in Site Health → Info via the debug_information filter (read-only tables). Attacks "defaults are invisible" (7 projects set $disable_search = true redundantly).

Note the two distinct Site Health extension points: site_status_tests for traffic-light tests, debug_information for the Info tab — the registry should feed both.

CLI mirror

wp timber-kit health --format=json — same registry, second adapter (precedent: src/Cli/PruneOriginalsCommand.php). Enables:

• CI gate — deploy passes only when the board has no criticals,
• fleet sweep — one script across all ~20 projects → the summary table the timber-kit 2.0 — planning meta-issue #66 audit produced by hand,
• headless runs sidestep the admin-access question entirely.

Registry + checks stay free of any Site Health dependency (the adapter is the only touchpoint), so the CLI adapter is small and every check is unit-testable.

Phasing (all 1.x-compatible behind the opt-in flag)

1. Skeleton: HealthCheck interface + Result + CheckRegistry + SiteHealthAdapter, $site_health flag.
2. Security category (verifies Security hardening: info-disclosure gaps vs WAF layer + optional security-headers emitter #40 hardening) + timber-kit category — highest value/effort ratio.
3. CLI adapter + fleet sweep script.
4. Remaining categories incrementally (caching / SEO / mail / performance / a11y).

Dropped from the original sketch: the "optional later" dashboard summary widget — Site Health + CLI already cover both audiences (admin manually, CI headlessly); a third surface isn't worth maintaining.