Keith Solomon
96 lines
4.8 KiB
Markdown
96 lines
4.8 KiB
Markdown
# WordPress Content Sync Implementation Roadmap
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement the linked plans task-by-task.
|
|
|
|
**Source Spec:** `docs/superpowers/specs/2026-04-25-wordpress-content-sync-design.md`
|
|
|
|
**Purpose:** Break the approved product design into independently shippable implementation plans.
|
|
|
|
## Delivery Strategy
|
|
|
|
Build the plugin in small vertical slices. Each slice must leave the repository in a working, testable state and must preserve the project agreements: PHPCS using `phpcs.xml`, PHPStan level 6 or higher, PHPUnit, secure nonce checks, sanitized input, escaped output, and no direct reliance on git or WP-CLI at runtime.
|
|
|
|
## Phase 1: Plugin Foundation
|
|
|
|
**Plan:** `docs/superpowers/plans/2026-04-26-wordpress-content-sync-foundation.md`
|
|
|
|
Creates the WordPress plugin skeleton, Composer/dev tooling, bootstrap loader, activation/deactivation hooks, service container, admin shell, settings persistence, logging, and initial PHPUnit coverage.
|
|
|
|
**Exit Criteria:**
|
|
- WordPress can load the plugin without fatal errors.
|
|
- Composer scripts exist for `lint`, `stan`, `test`, and `validate`.
|
|
- Admin menu renders a dashboard shell for users with `manage_options`.
|
|
- Plugin settings can be registered and read through a typed settings object.
|
|
- Unit tests pass for settings defaults, service registration, and logger behavior.
|
|
|
|
## Phase 2: URL Transformation
|
|
|
|
**Plan to create after Phase 1:** `docs/superpowers/plans/2026-04-26-wordpress-content-sync-url-transformer.md`
|
|
|
|
Adds domain mapping, URL replacement in post content, URL replacement inside serialized metadata, and GUID/permalink transformation rules.
|
|
|
|
**Exit Criteria:**
|
|
- Plain text URLs, HTML attributes, JSON strings, and serialized PHP arrays are transformed safely.
|
|
- Serialized data remains valid after replacement.
|
|
- Mapping supports multiple source/destination pairs.
|
|
- Tests cover escaped URLs, protocol-relative URLs, and nested metadata.
|
|
|
|
## Phase 3: Content Package Schema and File Transport
|
|
|
|
**Plan:** `docs/superpowers/plans/2026-04-26-wordpress-content-sync-file-transport.md`
|
|
|
|
Defines the sync package schema and implements export/import through JSON files for posts, pages, taxonomies, media metadata, and custom post type records.
|
|
|
|
**Exit Criteria:**
|
|
- Export produces a versioned JSON package with manifest, content records, taxonomy records, media records, and checksum metadata.
|
|
- Import validates schema before mutating data.
|
|
- Invalid files produce actionable admin errors without partial writes.
|
|
- File import uses WordPress nonce and capability checks.
|
|
|
|
## Phase 4: REST Transport
|
|
|
|
**Plan:** `docs/superpowers/plans/2026-04-28-wordpress-content-sync-rest-transport.md`
|
|
|
|
Adds authenticated REST endpoints and REST client support using WordPress application passwords.
|
|
|
|
**Exit Criteria:**
|
|
- Destination exposes secure receive/status endpoints.
|
|
- Source can test connection and send packages.
|
|
- REST failures surface typed errors and can fall back to file transport.
|
|
- Endpoint mutations validate permissions and request shape.
|
|
|
|
## Phase 5: Sync Engine and Content Handlers
|
|
|
|
**Plan:** `docs/superpowers/plans/2026-04-28-wordpress-content-sync-engine-handlers.md`
|
|
|
|
Implements orchestration, content extraction/import handlers, conflict detection, retries, progress state, and operation logs.
|
|
|
|
**Exit Criteria:**
|
|
- Push and pull operations can sync posts, pages, custom post types, taxonomies, metadata, and media records.
|
|
- Last-write-wins conflict behavior is logged.
|
|
- Partial failures preserve operation state.
|
|
- Long-running work is chunked to avoid memory exhaustion.
|
|
|
|
## Phase 6: Admin Workflow and Hardening
|
|
|
|
**Plan to create after Phase 5:** `docs/superpowers/plans/2026-04-26-wordpress-content-sync-admin-hardening.md`
|
|
|
|
Completes the admin UI, connection diagnostics, operation history, import/export screens, user-facing errors, debug logging controls, and smoke/integration tests.
|
|
|
|
**Exit Criteria:**
|
|
- Users can configure sync pairs, credentials, URL mappings, content type selection, and sync direction.
|
|
- Every state-changing admin action verifies nonce and capability.
|
|
- Output is escaped and input is sanitized.
|
|
- Manual smoke checklist covers production-to-staging, staging-to-production, REST, and file fallback.
|
|
|
|
## Cross-Phase Standards
|
|
|
|
- Keep implementation files under `src/` with namespace `WPContentSync`.
|
|
- Keep tests under `tests/Unit` and `tests/Integration`.
|
|
- Keep admin templates under `templates/admin`.
|
|
- Use `wpcs_` as the option/transient/action prefix for this plugin.
|
|
- Prefer interfaces at boundaries: settings storage, logger, transport, handlers, package validation.
|
|
- Never store raw application passwords in logs.
|
|
- Never mutate WordPress content from an unauthenticated request.
|
|
- Every plan should include test-first steps and exact verification commands.
|