Fix poisoned capabilities cache before and after Hiive connect

[mr-vara]

Summary

• Only treat capabilities cache as valid when it includes canAccessAI (marker for a real Hiive response)
• Do not cache failed capability fetches; return empty until a successful Hiive response
• Clear nfd_site_capabilities when connect succeeds so the next admin load refetches from Hiive
• Remove the bootstrap fallback that stored only canMigrateSite and hasAISiteGen for 4 hours
• When applying PATCH updates with invalid/empty cache, fetch from Hiive first if the site is connected

Problem

On first admin load, wp-module-runtime requests capabilities before connect completes. Failed fetches were cached (or replaced by a 2-key Bluehost fallback), so sites could be connected to Hiive while canAccessHelpCenter and other capabilities stayed missing for up to 4 hours.

Test plan

• vendor/bin/phpunit tests/wpunit/includes/SiteCapabilitiesWPUnitTest.php (in wp-browser env)
• Fresh site: load wp-admin before connect, then connect — capabilities should include canAccessHelpCenter
• Site with poisoned 2-key cache: load wp-admin when connected — should refetch full capabilities from Hiive without manual option delete
• Confirm GET /sites/v1/capabilities still works for connected sites

[github-actions]

AI code review

✅ Strengths

• Clear, principled fix for the poisoned capabilities cache: only treat caches as valid when they include a known Hiive marker (canAccessAI), don’t cache failures, and refetch before PATCH updates when prior cache is invalid.
• Sensible operational behavior change: clear nfd_site_capabilities immediately after a successful connect, ensuring the next admin load reflects the authoritative Hiive state.
• Removal of the temporary bootstrap fallback reduces long-lived partial state and aligns behavior across brands.
• Nice correctness fix in HiiveConnection::hiive_request: returning the recursive call result on reconnect avoids silently discarding responses.
• Good test coverage improvements: tests for not caching WP_Error/401, refetching when legacy 2-key cache is present, clearing on connect, and rejecting invalid capability sets. The WP_Mock adjustments make the expectations more robust.

⚠️ Suggestions (non-blocking)

• In HiiveConnection::hiive_request, guard against non-JSON or missing message keys before comparing to "Invalid token for url" (e.g., check is_array($body) && isset($body['message'])) to avoid PHP notices from malformed responses.
• Consider limiting reconnect-and-retry to a single attempt (e.g., a parameter or loop with maxAttempts = 1) to prevent potential infinite recursion if the API repeatedly returns the same "Invalid token for url" response despite reconnect succeeding.
• Consider defining a dedicated constant for the transient key (e.g., TRANSIENT_KEY = 'nfd_site_capabilities') in SiteCapabilities to reduce duplication and typo risk; tests can reference the constant for consistency.
• Prefer injecting SiteCapabilities (or retrieving from the container) in HiiveConnection::connect rather than instantiating directly; this helps testing, consistency, and future changes to the caching strategy.
• Add a unit test for SiteCapabilities::update when the cache is invalid and the site is connected, asserting that it fetches before merge and then sets the merged result.
• Documentation: note the new validity requirement (presence of canAccessAI) and that failed/partial responses are not cached, so readers of docs/index.md know why caches may appear empty until a successful Hiive round-trip.
• Optional: add minimal debug logging when rejecting a capabilities set as invalid or when clearing on connect, to aid troubleshooting in the field.

❌ Issues (potential risks to watch)

• The recursion in hiive_request after reconnect could loop indefinitely if the remote consistently returns the same invalid-token error. Recommend a single retry cap. Severity: medium, but edge-case; can be a quick follow-up patch.

Verdict

⚠️ Verdict: Merge with minor follow-ups. The changes address the core cache poisoning issue and improve correctness and tests. Please consider the small hardening around error handling in hiive_request and adding a retry cap; those can land in a follow-up if timing is tight.

---

Automation note: This AI review is posted as one regular pull-request conversation comment and is updated in place by the workflow on each run; it does not submit or dismiss formal GitHub Reviews.

[github-actions]

Coverage: Base 32.94% → PR 33.17% (must not decrease).
✅ No decrease.

project coverage report 33.17% @ ae54d67