← Back to directory

wordpress.md

implementation/wordpress.md · 12.5 KB · 2026-11-02 12:48

WordPress Implementation Knowledge

Scope and Authority

Status: backend-specific source observations and implementation requirements, 2026-09-11; not a new-platform support commitment. WordPress is an existing adapter candidate. Its inclusion, timing and depth remain content backends and MVP depth. There is no inherited requirement for 40+ clients, permanent WordPress support, a native-CMS replacement deadline or a migration program. Core contracts belong to communication and integrations, views and content, AI, and identity and governance. Tools and integration configuration follow objects and types; this document does not introduce a second foundational representation. Documentation authority and source lineage follow documentation governance and the source map.

Observed Content Flow

1. Connect an HTTPS WordPress site using a dedicated username/application password. 2. Test authenticated access to /wp-json/wp/v2/users/me. 3. Discover the selected site's blocks, templates, template parts, saved patterns and publicly accessible styles. 4. Store an old-application discovery snapshot and inspect its resources in the builder. 5. Manually assemble or optionally generate Gutenberg markup, then sanitize it. 6. Save unfinished work locally, resume/discard a saved action, or request a WordPress draft. 7. Record selected activity and expose the returned WordPress edit link.

The former legacy WordPress adapter handled these operations through request controllers; that implementation has been removed and is retained only as historical context here. The current paths use old organization/selected-client/admin checks. Retain the isolation requirement, not the schema, role hierarchy or URL contract. These operations run in request handlers; no general job processor or reliable external-effect transaction is established by their presence.

Discovery Coverage and Limits

| Resource | Observed source and retained data | Limitation | | --- | --- | --- | | Block types | /wp-json/wp/v2/block-types?context=view; names and titles | Attribute schemas, validation and examples are not retained as a complete tool contract | | Templates | /wp-json/wp/v2/block-templates, then /wp-json/wp/v2/templates | Availability varies by WordPress version, theme and permissions | | Template parts | /wp-json/wp/v2/template-parts, then /wp-json/wp/v2/block-template-parts | Optional calls can collapse errors into empty results | | Saved patterns | /wp-json/wp/v2/blocks?context=edit&per_page=100; normalized name/id/slug | Not exhaustive theme/plugin pattern discovery; no general pagination loop | | Public styles | Homepage stylesheet links and bounded CSS fetches | A sampled stylesheet view, not the full theme/editor style system |

The empty-block fallback names core/paragraph, core/heading, core/image, core/list and core/quote. Treat it as an assumption to inspect, not proof that authenticated discovery succeeded or that all those tools are valid on the target. The initial block request can fail; fallback behavior does not turn every failed discovery into a usable snapshot. Optional endpoint failures are swallowed by optionalResource; an empty list does not distinguish unsupported, unauthorized, unavailable and truly empty. Future tooling must report these states separately so partial discovery cannot masquerade as complete support.

Stylesheet discovery limits the homepage and each stylesheet to 524,288 bytes, follows at most 12 linked stylesheets and does not follow redirects. It retains up to 24 color references, 16 CSS color-variable entries and 12 font-family entries per stylesheet, plus summary labels. Fonts include the declaration and a limited resolved CSS-variable value; these are styling cues, not a browser-computed design system. External CDN styles, inline/editor-only styles, nested imports, dynamic styles and complete cascade/variable resolution are not established coverage. The helper is named resolveSameOriginUrl, but checks HTTPS and hostname rather than a complete scheme/host/port origin equality test; do not overstate the boundary. Theme/plugin REST capabilities, permissions and endpoint differences must be captured in per-site results rather than silently generalized.

Per-Site Normalized Tools

Build the authorized tool set for the selected connection and its discovered state; availability on one site does not imply availability on another. The current discovery representation is intermediate metadata, not the completed normalized platform tool model. A future adapter mapping must supply:

Generation and approval should consume the normalized contract, not raw WordPress API payloads or provider-specific prompt rules. Backend-specific markup conversion remains the WordPress adapter's responsibility. Coverage measures the useful resource set recognized; fidelity measures whether recognized tools accurately express fields, structure, style and valid usage. Prefer a smaller reliable set over broad uncertain exposure. Flag or omit resources that cannot be normalized faithfully. Recognition, successful insertion and valid WordPress round-trip rendering are different checks.

Generation and Manual Editing

The removed legacy content-generation controller required authorization, CSRF, a title, a scoped site and a completed discovery snapshot. Its rate-limiter call permits 30 generation attempts per 3,600 seconds for an organization/user/site subject; this is a legacy limiter use, not platform-wide abuse protection. The adapter currently sends bounded block/template/pattern labels and style cues to Groq; complete normalized schemas and examples are not sent. Prompt limits currently include 30 block labels and 10 template/pattern labels each; style context is also sampled. Prompt instructions are not a validator, and sanitized HTML is not necessarily structurally valid Gutenberg content. The removed legacy generation path passed output through its sanitizer; independently test block structure, allowed tools, attributes and render fidelity before any future automation can rely on it.

GROQ_API_KEY is optional; missing configuration returns an unavailable generation status instead of establishing a dependency for manual editing. GROQ_MODEL and GROQ_API_URL configure the old provider call; exact defaults are in configuration. Keep provider credentials out of prompts and responses. A future provider-neutral boundary must preserve deterministic validation and authorized execution. Core read/edit/save behavior must remain available without AI; generation failure should leave the author's draft intact. The UI system owns the shared builder/preview interaction pattern, not this backend document.

Drafts, Approval and External Effects

createDraft posts title/content with status: draft to /wp-json/wp/v2/posts or /wp-json/wp/v2/pages. This is draft creation, not live publication; old method variables or error labels containing publish do not change that behavior. The handler can mark a saved action completed and record activity after the remote response, but those local changes are not atomic with the remote request. A timeout after WordPress accepts a request can leave the outcome uncertain; repeated submission can create another draft without an approved idempotency strategy. Do not imply reliable retries, duplicate prevention, rollback or exactly-once effects from the current flow. Approval semantics belong to identity/governance; scheduling, retries and execution binding belong to workflows and automation. The existing implementation does not establish a generic approval queue, publishing scheduler, revision synchronization or automated metrics collection. Expose local-save, remote-draft, uncertain-result and live-publication states distinctly when their respective behaviors exist.

Security and Outbound Requests

Use HTTPS with certificate verification and dedicated application passwords with the narrowest useful WordPress role/capabilities. The current URL validator rejects embedded credentials, non-HTTPS URLs, private/reserved literal IPs and a private/reserved result from gethostbyname. This is partial SSRF mitigation, not proof against DNS rebinding, multiple address records, IPv6 or destination changes between validation and connection. Review the actual connected address, ports, redirects, DNS resolution and network egress policy before trusting arbitrary site URLs. Authenticated requests disable redirects and use Basic authentication over TLS; plaintext credentials are decrypted for request use only. Current timeouts are 8 seconds to connect, 15 seconds for connection tests, 20 seconds for authenticated resources/drafts and 12 seconds for public assets. Groq calls use separate 10-second connect/45-second overall limits; these do not define future platform-wide budgets. The public-asset body limit is not a general authenticated-response limit; establish bounded responses and parsing rules for the adapter as a whole.

Application passwords are encrypted using current AES-256-GCM, not the proposed libsodium alternative; see secrets and encryption. Never display stored passwords or include them in discovery snapshots, error messages, logs, model context or export data. Use independently revocable credentials per site/purpose; blank edit fields should not require exposing the current secret. Verify credential replacement, revocation, scope isolation, cross-site saved-action access and log redaction with isolated fixtures. Capture site/action/actor/time/result for audit without secret values; history semantics remain with time and events.

Lifecycle Specification and Acceptance

Settled contract: per-context tool validity, explicit revisions, governed delivery and recovery. Chosen mechanism for later adapter work: store normalized tools as typed objects linked to source site/discovery snapshot and revision; cache derived render data only. Refresh on explicit discovery and before delivery when the recorded site capabilities changed; unavailable verification blocks delivery rather than using an unverified fallback. Retire removed tools, retain saved references and require revalidation/manual review for incompatible changes. These mechanisms are not yet built.

Initial remote create is treated as non-safely-repeatable unless a tested adapter can demonstrate deterministic server-side idempotency. Timeout after possible creation remains Unknown/Reconciliation; inspect authoritative remote evidence or obtain a governed recovery determination before another create. The old draft implementation does not establish this new runtime contract. No live WordPress operation is required for the first milestone. Before claiming support, record authenticated/unauthorized/partial discovery, per-site variation, normalized-schema validity, unsupported-tool handling, render-back fidelity, draft-only effects, missing-AI behavior and SSRF/redaction checks. No automated WordPress integration suite is currently configured, and no live WordPress operation was performed for this documentation. This limitation is separate from the platform's focused PHPUnit suite. Separate new-platform evidence from adapter reuse in status; historical UI availability is not acceptance of a backend contract.