Adds a PHP/SQLite history server in server/ and refactors the plugin to
write every session change through it. Healthcheck history now survives
plugin uninstall and groups across dev + live URLs for the same engagement
via an editable site_key (defaults to the normalised host).
Server (server/):
- Front controller + hand-rolled autoloader, no framework, no composer
- SQLite default DSN; swap to MySQL by changing config.php
- Schema: healthchecks (PK id, UNIQUE (site_key, started_at)) + step_updates
(PK (healthcheck_id, step_id)) + request_log; auto-migration runner
- 8 endpoints: POST/GET/PUT healthchecks, PUT/GET step rows, GET step history
with exclude_id, GET /sites (recent), GET /step-counts (badge data)
- Bearer auth via hash_equals; HTTPS expected (plugin enforces client-side)
- DEPLOY.md with Apache/nginx vhosts, Let's Encrypt, SQLite backup cron,
and the /home/www/ perm gotcha
- dev-router.php works around PHP -S 405-ing dotted uniqid paths
Plugin:
- ATT_HC_Api HTTP client reads ATT_HC_API_URL/ATT_HC_API_KEY constants
from wp-config.php; refuses non-HTTPS with a loopback dev exception
- ATT_HC_Session is now write-through: every start/update_step/finish/
set_autocheck POSTs or PUTs to the server first, then updates the local
WP option cache. No drift possible — failures throw ATT_HC_Api_Exception
- previous() now reads from /healthchecks?include=steps and reconstructs;
the old att_hc_previous_session local option is gone
- ATT_HC_Session::resume(id) hydrates a server session into the local cache
- Start screen: editable site_key (defaults to normalise_site_url()),
datalist of recent engagements, table of in-progress sessions for the
chosen key with Resume buttons. Double-click guard on start + resume
handlers short-circuits if a session is already active
- Per-step <details> disclosure shows "Previous notes (N)" badge from
/step-counts; lazy-loads detail rows on first expand via admin-ajax,
caches via data-loaded, resets on error so user can retry
- All admin handlers catch ATT_HC_Api_Exception and surface via
att_hc_api_error transient → admin notice
- Hard config-error gate at the top of the admin page blocks the UI when
ATT_HC_API_URL/ATT_HC_API_KEY are missing or malformed
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Wholesale rename to avoid clashes with generic 'site healthcheck'
plugin names on a target site:
- Plugin Name: 'Site Healthcheck' → 'ATT Site Healthcheck'
- Main file: site-healthcheck.php → att-site-healthcheck.php
- Plugin folder: site-healthcheck → att-site-healthcheck
- Admin menu slug: site-healthcheck → att-site-healthcheck
- Settings slug: site-healthcheck-settings → att-site-healthcheck-settings
- PHP class prefix: WPH_ → ATT_HC_
- Function prefix: wph_ → att_hc_
- Option / transient: wph_* → att_hc_*
- Action/filter: wph_* → att_hc_*
- CSS class prefix: wph- → att-hc-
- Constants: WPH_GITEA_* → ATT_HC_GITEA_*
- Class file names: class-wph-*.php → class-att-hc-*.php
- Dev folder: ~/dev/wp-healthcheck → ~/dev/att-site-healthcheck
Existing in-progress sessions on installs that had the old wph_session
option will not migrate — they were intended for dev use only and the
user has confirmed this is OK for the rename window.
Smoke-tested on testsite: classes load, 14 steps discovered, save/load
round-trip works, admin page renders with new att-hc- CSS classes.
Recovery plugin detection unchanged — that lives in wp-site-recovery
and continues to be detected by Name + Author header.
Step 3 (Core) now does three independent lookups:
- Installed version (the truth, from $wp_version)
- Latest per WordPress (via get_core_updates — what WP_Downgrade can
manipulate)
- Latest per wp.org (direct call to api.wordpress.org/core/version-check/1.7/
cached 1h, can't be cloaked from the server side)
If 'Latest per WordPress' < 'Latest per wp.org', the finding is bumped
to bad with a CLOAKED detail message. The wp_downgrade_core_version
option is also surfaced verbatim so it's obvious where the pin lives.
Step 4 (Plugins) similarly:
- wp_org_info() now captures the version field from the WP.org plugins
info API. Cache key bumped to wph_pi2_ so existing entries get
re-fetched.
- For each plugin: installed version vs wp.org reported version.
- If installed < wp.org AND the WP update_plugins transient doesn't
flag it, the row is bad with 'CLOAKED — WP says up-to-date'.
- Cloaked count surfaces in the summary.
Both steps also explicitly detect a roster of known cloaker plugins
(WP Downgrade, WP Rollback, Easy Updates Manager, Disable Updates
Manager, Stops Core/Theme/Plugin Updates, Companion Auto Update)
and warn when any are active, so the technician sees the framing
before diving into individual rows.
Smoke-tested with WP Downgrade installed and wp_downgrade_core_version
set: both findings fire correctly, target version is surfaced.
The step card's save form wrapped the entire card, including the
autocheck 'Run checks' button and per-step extras like the email
'Send' form — those are also <form> elements. Nested forms are
invalid HTML; browsers silently drop the outer form's submit when
they see an inner one.
So clicking 'Save step' was effectively a no-op: the POST to
wph_save_step never reached the server, and the status reverted to
'not started' on reload. The bug had been there since the autocheck
panel was introduced in v0.3 of the healthcheck.
Restructured the step card as a <div> wrapper containing three
siblings: (1) static content (title, blurb, sub-items, watch-outs,
escalation), (2) the autocheck panel + step render_extra (each with
their own forms), (3) the save form. No nesting anywhere.
Verified end-to-end on testsite: step status and notes now persist
across page loads. The email step (which has 3 sibling forms — refresh
checks, send test, save) also renders without nesting.
The old #1a8917 green and 0.6rem dots were subtle enough on some
displays to read as dark grey. Bumping to a vivid #16a34a, 0.75rem
diameter, with a faint inset shadow for crispness on light
backgrounds. Other states adjusted to match the same brighter palette
(amber #f59e0b skipped, red #dc2626 blocked, neutral #9ca3af n/a).
Also dims the link text to a dark green for done rows via :has()
so the whole line reads as 'this is complete'.
Replaces the 'inactive themes count' finding with a clearer breakdown:
Keep set (each gets a 'Keep — <why>' row):
- The active theme (always)
- The parent of the active theme (if a child theme is in use and
the parent exists on disk)
- The newest Twenty* default installed (as a fallback we can swap
to if the active theme breaks during work)
Removal candidates (one row per inactive theme not in the keep set):
- 'Candidate' rows for the technician to walk down and remove
- Summary line warns at >3 candidates
- 'none' ok row if every installed theme is a keeper
Smoke-tested on testsite with three configurations:
- Default theme active, no child: keep active + Twenty Twenty-Five
fallback; one removal candidate.
- Cluttered (Astra + Hello Elementor + extra Twenty* installed):
same keepers, 4 candidates surfaced.
- Astra active (custom, no child): keep Astra + Twenty Twenty-Five
fallback; 4 candidates including any unused Twenty* and Hello
Elementor.
Same as the matching change in wp-site-recovery — excludes .beads/,
.claude/, AGENTS.md, CLAUDE.md, .gitignore, .gitattributes itself,
and steps.md (technician guide, not used at runtime) from any release
archive.
Detection (recovery-bootstrap.php):
- Match on plugin Name + Author instead of hard-coded folder slug, so
the recovery plugin is found regardless of whether it was unpacked
as site-recovery/, wp-site-recovery/, or anything else.
One-click install (recovery-installer.php — new):
- Pulls site-recovery from a private Gitea repo via the standard archive
endpoint with token auth.
- Ref resolution order: latest release → latest tag → main branch HEAD.
Lets us tag pinned releases in Gitea later without changing code.
- upgrader_source_selection filter forces the unpacked folder name to
'site-recovery' regardless of the gitea wrapper-folder suffix.
- Config from constants in wp-config.php (WPH_GITEA_HOST/OWNER/REPO/TOKEN)
beats DB option storage. Constants are visually locked in the settings
UI so admins can see they're inherited.
Settings page (hidden submenu, reachable at Tools → Site Healthcheck
→ 'Configure gitea source'):
- Host / Owner / Repo / Token fields
- Inline 'Install now' button when configured + plugin not installed
Bootstrap status panel:
- Shows the recovery plugin's actual file path when active
- 'Install from gitea (latest)' button when configured + missing
- 'Configure gitea source' button when not configured + missing
Install handler shows a success message via transient on the main
healthcheck page after a successful install + activate.
When debug capture is requested, the trace is now also appended to the
step's notes textarea with a clear --- SMTP debug trace ... --- header
and timestamp. This means:
- The technician can edit/trim the trace before finishing the session.
- It flows naturally into the Markdown + HTML report via the existing
notes-in-report rendering — no special-casing needed.
- Pre-existing notes are preserved (appended to, not overwritten).
- Status is preserved.
- The collapsible details block on the step card still shows the raw
capture for quick reference.
Checkbox on the send-test form turns on PHPMailer SMTPDebug=2 for one
send only. A Debugoutput callback captures the wire conversation;
hook is removed immediately after wp_mail returns.
AUTH credentials redacted: lines containing 'AUTH' or 16+ char base64
strings get replaced. Trace capped at 200 lines and stashed on the
session. Rendered as a collapsible <details> block on the step card.
Transport type (mail/smtp/etc., read from PHPMailer->Mailer) surfaced
in the finding detail so the technician knows whether a trace will
contain useful SMTP traffic — only the smtp transport emits any.
Demonstrates the drop-in pattern: adding a step with a form is a single
new file under includes/steps/, plus one small extension to the base
abstraction.
WPH_Step gains:
- render_extra($session_state) — emit extra HTML inside the step card
- handle_action($name, $input) — handle a step-specific POST and
return a finding to record
New generic admin-post handler wph_step_action routes form submissions
to the matching step's handle_action() with nonce verification.
The email step (includes/steps/115-email.php):
- Detects 7 known SMTP plugins, surfaces default From address
- Renders a To: input prefilled with the current admin's email
- Sends via wp_mail() with wp_mail_failed capture so failures show the
underlying error
- Records the outcome as a 'last_send' finding so it appears on the
step card, in the summary, and in the downloadable report
Infrastructure:
- WPH_Step::autocheck($session_state) returns an array of findings
shaped {id, level: ok/warn/bad/info, label, value, detail}.
- WPH_Session stores results keyed by step id (persisted in the option-
backed session).
- WPH_Step::has_autocheck() reflection check so the UI only renders the
panel for steps that implement automation.
- 'Run checks' / 'Refresh' button per step, admin-post handler runs
autocheck() and stashes the result on the session.
- Findings rendered as a coloured table on the step card; included
verbatim in the Markdown report with status icons.
Step automations implemented:
- Step 1 (Backup): detection of 11 known backup plugins by slug;
active/inactive state; UpdraftPlus last-backup timestamp.
- Step 2 (Environment): PHP version + EOL, WP version vs latest, disk
usage, wp-config flags, file perms on wp-config/wp-content/uploads,
error-log sizes.
- Step 4 (Plugins): WP.org API enrichment with 24h transient cache —
last_updated, active_installs, abandonment flag, removed-from-repo
flag, update-available count. Summary line at the top.
- Step 8 (Security): SSL cert expiry via stream_socket_client +
openssl_x509_parse, administrator audit, xmlrpc reachability, login
URL hardening detection.
- Step 9 (Database): spam comments, post revisions, autoload size (WP
6.6+ value handling), top 3 largest tables.
- Step 11 (Small fixes): deactivated-but-installed plugin list,
homepage alt-text scan.
Smoke-tested on testsite — all six steps return findings with
correctly-classified levels. Report regenerated with automated findings
section.
Plugin skeleton, drop-in step registry, option-backed session, single-page
checklist UI, downloadable Markdown report. Steps live as one file each
under includes/steps/ — adding/removing one is a single file change.
Step IDs are stable strings so renaming files preserves session data.
Architecture (hc-5ix.3): WPH_Steps singleton globs includes/steps/*.php,
natsort-orders by filename, requires each file (which returns a WPH_Step
instance), then applies a 'wph_steps' filter so installs can drop steps.
Session (hc-5ix.4): option-backed (per decision — plugin is installed
per-engagement, so DB-resident history would be lost on uninstall).
Single in-progress session per site; finished sessions render a report
that the user downloads/copies.
Recovery bootstrap (hc-5ix.1): detects whether wp-site-recovery is
installed + active, surfaces state on the start panel and in every
active session. Manual install for now; private update channel deferred
to hc-5ix.27.
Smoke-tested on testsite: registry discovery (13 steps in correct order),
start → update_step → progress count → finish → 8KB Markdown report →
discard cycle.
