muninn/docs/superpowers/specs/2026-07-19-wordpress-publish-design.md

WordPress Publishing — Design

Purpose

Extends the existing Sites & Posts data model so a Site can be marked as a WordPress-powered CMS with its own REST API credentials, and adds an Artisan command that publishes an existing draft/scheduled Post to that site via the WordPress REST API. This is the WordPress equivalent of the reddit-post sidecar, but implemented natively in Laravel rather than as an external Playwright process, since WordPress's REST API is a direct HTTP call and the Post/Site data already lives in this app's database.

Scope

• Distinguish a Site's CMS by a cms_type field: wordpress, custom, or other.
• Store WordPress Application Password credentials (wp_username + wp_app_password) on a Site.
• Add php artisan posts:publish {post} — loads a Post by ID, publishes it to its Site's WordPress REST API, and updates the Post's status and published_url.
• Update the Sites Livewire UI to manage cms_type and the WordPress credential fields.
• Expose the new Site fields via the existing read-only Sites API, and the new Post field via the existing Posts API.

Out of scope:

• Any CMS integration beyond WordPress — custom and other are labels only, with no publish path.
• Updating/editing an already-published WP post, deleting a WP post, or any WP endpoint beyond creating a post.
• Media/image uploads, categories, tags, excerpts, or any WP post field beyond title/content/status.
• Scheduled publishing via WP's own future post status — this command always publishes immediately (status: publish) when invoked; scheduling is this app's own Post.scheduled_at + AI-driven polling, unchanged from the existing design.
• Authentication/authorization on the command, UI, or API (consistent with the rest of the app — local network only).
• Any plugin-based WP auth scheme (JWT, API-key plugins) — Application Passwords (built into WordPress core 5.6+) only.

Data Model

sites table — new columns

Column	Type	Constraints
cms_type	string (enum)	required, default custom — one of: wordpress, custom, other
wp_username	string	nullable
wp_app_password	string	nullable, plain text (no hashing/encryption — same precedent as social_accounts.password)

wp_username/wp_app_password are only meaningful when cms_type = wordpress; no DB-level constraint enforces this pairing (validated at the UI/command level instead).

posts table — new column

Column	Type	Constraints
published_url	string	nullable — set on successful publish; generic across future publish targets, not WordPress-specific

Command: php artisan posts:publish {post}

Arguments: one required argument, the Post id.

Flow:

1. Load the Post by id (404/"post not found" error and exit 1 if missing). Eager-load its site relation.
2. Validate, in order, failing fast with a descriptive message and exit code 1 on the first failure:
   • post.type === 'blog' — else "Post {id} has type '{type}', expected 'blog' to publish to a CMS."
   • post.site.cms_type === 'wordpress' — else "Site '{name}' is not configured as WordPress (cms_type={cms_type})."
   • post.site.wp_username and post.site.wp_app_password are both present — else "Site '{name}' is missing WordPress credentials."
   • These three pre-flight checks happen before any DB write to the Post — a mismatched post/site pairing is a usage error, not a publish failure, so the Post's status is left untouched in these cases.
3. Send POST {site.url}/wp-json/wp/v2/posts via Guzzle, HTTP Basic Auth (wp_username / wp_app_password), JSON body:

   { "title": post.title, "content": post.body, "status": "publish" }
   

4. On success (2xx response with a link field in the JSON body):
   • Update the Post: status = 'published', published_url = response.link.
   • Print {"success": true, "url": "<published_url>"} to stdout, exit 0.
5. On failure (network/connection error, non-2xx response, or malformed response missing link):
   • Update the Post: status = 'failed'.
   • Print {"success": false, "error": "<description>"} to stdout, exit 1.
   • Error description includes the WP error message when the response body has one (WP REST errors return {code, message, data}), otherwise a generic description of the failure (e.g. "could not connect to site", "unexpected response from WordPress").

Title handling: Post.title is nullable in the existing schema, but WordPress requires a title. If post.title is null/empty at step 3, this is a pre-flight validation failure (same category as step 2): "Post {id} has no title, required to publish to WordPress." — exit 1, Post status untouched.

UI (Livewire)

Sites create/edit form gains:

• CMS Type — dropdown: WordPress / Custom / Other (default Custom).
• When WordPress is selected, two additional fields appear:
  • WP Username — text input.
  • WP Application Password — masked input with reveal toggle (same convention as the Social Accounts password field). Not required at the DB level, but the form validates both are present together when cms_type = wordpress is submitted (client-side/Livewire validation — DB stays nullable to avoid migration headaches if a site is later switched away from WordPress).

Sites table view gains a CMS Type column. No changes to the Posts UI (the new published_url field is visible as a link in the Posts table's existing "actions" area or a new column — small addition, decided at plan time).

API

No new endpoints.

• GET /api/sites / GET /api/sites/{id} — SiteResource now also returns cms_type, wp_username, wp_app_password (plain text), consistent with the existing precedent that Social Accounts' API already returns plain-text passwords, since the AI agent needs credentials to act directly.
• GET /api/posts / GET /api/posts/{id} — response shape gains published_url.

Testing / Edge Cases

• Feature test: posts:publish on a post with type != 'blog' fails with the expected message, exit 1, Post status unchanged.
• Feature test: posts:publish on a post whose site has cms_type != wordpress fails accordingly, Post status unchanged.
• Feature test: posts:publish on a WordPress site missing credentials fails accordingly.
• Feature test: posts:publish on a post with no title fails accordingly.
• Feature test: successful publish (mocked HTTP via Guzzle's mock handler / Laravel's Http::fake equivalent) — asserts Post updated to status=published with correct published_url, and the printed JSON/exit code are correct.
• Feature test: WP API returns an error response (e.g. 401 invalid credentials, 500) — asserts Post updated to status=failed, correct error message surfaced, exit 1.
• Feature test: WP API unreachable (connection exception) — asserts graceful failure, status=failed, exit 1.
• Livewire test: Sites form shows/hides WP fields based on cms_type selection, and validates the paired-fields rule.
• Migration test/manual check: existing sites default to cms_type=custom with null WP fields (no backfill needed beyond the column defaults).