feat: scaffold plugin foundation
This commit is contained in:
Keith Solomon
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,95 @@
|
||||
# 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 to create after Phase 2:** `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 to create after Phase 3:** `docs/superpowers/plans/2026-04-26-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 to create after Phase 4:** `docs/superpowers/plans/2026-04-26-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.
|
||||
@@ -0,0 +1,293 @@
|
||||
# WordPress Content Sync Plugin Design
|
||||
|
||||
**Date:** 2026-04-25
|
||||
**Type:** Feature Design
|
||||
**Status:** Approved
|
||||
|
||||
## Overview
|
||||
|
||||
A WordPress plugin that enables bidirectional content synchronization between two WordPress instances, supporting both REST API and file-based transfer methods. The plugin handles all content types including posts, pages, custom post types, taxonomies, and media, with automatic URL rewriting for domain changes.
|
||||
|
||||
## Use Case
|
||||
|
||||
Primary use case is syncing content between production and staging/development environments for developers building and maintaining WordPress sites. The plugin must work with instances that are not publicly accessible and where git or wp-cli are unavailable.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Layers
|
||||
|
||||
**Core Sync Engine**
|
||||
- Orchestrates sync operations between instances
|
||||
- Manages both REST API and file transfer methods
|
||||
- Coordinates source and destination operations
|
||||
- Handles error recovery and retry logic
|
||||
|
||||
**Content Handlers**
|
||||
- Separate modules for different content types
|
||||
- Each handler extracts, transforms, and restores specific content
|
||||
- Supports posts, pages, media, custom post types, taxonomies, metadata
|
||||
|
||||
**URL Transformation Layer**
|
||||
- Handles all URL rewriting during sync operations
|
||||
- Supports automatic domain mapping and manual overrides
|
||||
- Processes content links, image paths, and custom field URLs
|
||||
|
||||
**Transport Layer**
|
||||
- Abstracts communication method between instances
|
||||
- REST API implementation with application password authentication
|
||||
- File transfer implementation as fallback
|
||||
|
||||
**Admin Interface**
|
||||
- WordPress admin pages for configuration
|
||||
- Sync operation management and monitoring
|
||||
- Status reporting and error handling
|
||||
|
||||
## Core Components
|
||||
|
||||
### Sync Manager
|
||||
Central orchestrator responsible for:
|
||||
- Managing sync configuration (instance pairs, credentials, URL mappings)
|
||||
- Determining transport method (REST API vs file transfer)
|
||||
- Coordinating content handlers during sync operations
|
||||
- Handling error recovery and retry logic
|
||||
- Providing sync status and progress reporting
|
||||
|
||||
### Content Handlers
|
||||
Specialized processors for different content types:
|
||||
|
||||
**Posts/Pages Handler**
|
||||
- Standard WordPress content with revisions
|
||||
- Handles post content, excerpts, titles, and status
|
||||
- Manages post relationships and hierarchy
|
||||
|
||||
**Media Handler**
|
||||
- File uploads and attachments
|
||||
- URL rewriting for media references
|
||||
- Handles image sizes and metadata
|
||||
|
||||
**Custom Post Types Handler**
|
||||
- Dynamic CPT support
|
||||
- Respects CPT registration and capabilities
|
||||
- Handles CPT-specific metadata
|
||||
|
||||
**Taxonomies Handler**
|
||||
- Categories, tags, and custom taxonomies
|
||||
- Term relationships and hierarchies
|
||||
- Term metadata and descriptions
|
||||
|
||||
**Metadata Handler**
|
||||
- Post meta, user meta, and options
|
||||
- Serialized data handling
|
||||
- Custom field URL scanning
|
||||
|
||||
**Users Handler** (Optional)
|
||||
- User accounts and roles
|
||||
- User capabilities and permissions
|
||||
- User metadata
|
||||
|
||||
### URL Transformer
|
||||
Handles URL transformation during sync:
|
||||
- Domain mapping configuration (source → destination URLs)
|
||||
- Content body URL replacement (links, images, embedded content)
|
||||
- GUID and permalink updates
|
||||
- Custom field URL scanning
|
||||
- Serialized data URL replacement
|
||||
|
||||
### Transport Abstraction
|
||||
Two implementation strategies:
|
||||
|
||||
**REST API Transport**
|
||||
- Uses WordPress REST API endpoints
|
||||
- Application password authentication
|
||||
- Automatic when instances can communicate
|
||||
- Supports real-time sync operations
|
||||
|
||||
**File Transport**
|
||||
- Generates JSON packages with all content data
|
||||
- Manual file transfer between instances
|
||||
- Fallback when REST API unavailable
|
||||
- Supports offline sync scenarios
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Push Operation (Source → Destination)
|
||||
1. User initiates push from source instance admin
|
||||
2. Sync Manager validates destination connection
|
||||
3. Content handlers extract data from source database
|
||||
4. URL Transformer rewrites source URLs to destination URLs
|
||||
5. Transport layer sends data (REST API or generates file)
|
||||
6. Destination receives and processes data
|
||||
7. Content handlers import/merge data on destination
|
||||
8. Sync Manager reports completion status
|
||||
|
||||
### Pull Operation (Destination ← Source)
|
||||
1. User initiates pull from destination instance admin
|
||||
2. Destination connects to source instance
|
||||
3. Source extracts and transforms data
|
||||
4. Source sends data to destination
|
||||
5. Destination processes and imports data
|
||||
6. Sync Manager reports completion status
|
||||
|
||||
### File Transfer Flow
|
||||
1. Source instance exports data to JSON file
|
||||
2. User manually transfers file between instances
|
||||
3. Destination instance imports JSON file
|
||||
4. Same processing as REST API flow
|
||||
|
||||
### Conflict Resolution
|
||||
- Last-write-wins strategy for content conflicts
|
||||
- Optional merge strategies for specific content types
|
||||
- Conflict log for review after sync operations
|
||||
- User notification of conflicts requiring manual resolution
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Connection Errors
|
||||
- Automatic retry with exponential backoff for REST API failures
|
||||
- Graceful fallback to file transfer if REST API unavailable
|
||||
- Clear error messages with troubleshooting steps
|
||||
- Connection timeout handling
|
||||
|
||||
### Data Validation
|
||||
- Schema validation for imported JSON files
|
||||
- Content integrity checks during sync operations
|
||||
- Validation of required fields and relationships
|
||||
- Data type and format verification
|
||||
|
||||
### Partial Failure Recovery
|
||||
- Transaction-based sync operations with rollback on failure
|
||||
- Progress tracking for resumable sync operations
|
||||
- Detailed error logs with context for debugging
|
||||
- State preservation for interrupted operations
|
||||
|
||||
### User-Facing Error Messages
|
||||
- Specific error types (connection, authentication, data, transport)
|
||||
- Actionable suggestions for each error type
|
||||
- Error severity levels (warning, error, critical)
|
||||
- Contextual help and documentation links
|
||||
|
||||
### Logging and Debugging
|
||||
- Detailed sync operation logs
|
||||
- Performance metrics for optimization
|
||||
- Optional debug mode for troubleshooting
|
||||
- Log rotation and management
|
||||
|
||||
## Admin Interface
|
||||
|
||||
### Main Dashboard
|
||||
- List of configured sync pairs (source/destination instances)
|
||||
- Quick sync status indicators (last sync time, success/failure)
|
||||
- Push/Pull action buttons for each sync pair
|
||||
- Sync history and logs viewer
|
||||
- Overall system health indicators
|
||||
|
||||
### Configuration Pages
|
||||
|
||||
**Sync Pair Setup**
|
||||
- Add/edit source and destination instances
|
||||
- Instance naming and identification
|
||||
- Connection details and credentials
|
||||
|
||||
**Connection Test**
|
||||
- Verify REST API connectivity
|
||||
- Test authentication credentials
|
||||
- Validate URL mappings
|
||||
- Network diagnostics
|
||||
|
||||
**URL Mapping Configuration**
|
||||
- Define source/destination domain mappings
|
||||
- Multiple domain support
|
||||
- URL pattern matching
|
||||
- Custom replacement rules
|
||||
|
||||
**Content Type Selection**
|
||||
- Choose which content types to sync
|
||||
- Individual content type toggles
|
||||
- Bulk selection options
|
||||
- Custom post type detection
|
||||
|
||||
**Authentication Setup**
|
||||
- Application passwords and credentials
|
||||
- Secure credential storage
|
||||
- Credential rotation support
|
||||
- Permission verification
|
||||
|
||||
### Sync Operation Interface
|
||||
- Progress bar with real-time status updates
|
||||
- Content type breakdown (posts, media, etc.)
|
||||
- Error/warning notifications during sync
|
||||
- Cancel operation support
|
||||
- Detailed results summary after completion
|
||||
|
||||
### Settings and Preferences
|
||||
- Default sync direction preferences
|
||||
- Conflict resolution strategy selection
|
||||
- Automatic URL replacement toggle
|
||||
- Logging level configuration
|
||||
- Performance tuning options
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Testing
|
||||
- Content handler tests for each content type
|
||||
- URL transformer tests with various URL patterns
|
||||
- Transport layer tests for both REST API and file methods
|
||||
- Sync manager orchestration tests
|
||||
- Individual component isolation tests
|
||||
|
||||
### Integration Testing
|
||||
- End-to-end sync operations between test instances
|
||||
- REST API authentication and communication
|
||||
- File export/import functionality
|
||||
- URL rewriting accuracy across different content types
|
||||
- Multi-instance sync scenarios
|
||||
|
||||
### Edge Case Testing
|
||||
- Large content sets (performance testing)
|
||||
- Special characters and encoding issues
|
||||
- Custom post types and taxonomies
|
||||
- Plugin/theme compatibility
|
||||
- Network connectivity issues
|
||||
- Concurrent sync operations
|
||||
|
||||
### Manual Testing Scenarios
|
||||
- Production to staging sync
|
||||
- Staging to production sync
|
||||
- File transfer fallback
|
||||
- URL replacement accuracy
|
||||
- Conflict resolution behavior
|
||||
- Error recovery procedures
|
||||
|
||||
## Technical Requirements
|
||||
|
||||
### WordPress Compatibility
|
||||
- Minimum WordPress version: 5.6+
|
||||
- PHP version: 7.4+
|
||||
- REST API support required
|
||||
- Application passwords feature required for REST API method
|
||||
|
||||
### Performance Considerations
|
||||
- Support for large content sets (1000+ posts)
|
||||
- Efficient memory usage during sync operations
|
||||
- Background processing for long-running operations
|
||||
- Progress tracking for user feedback
|
||||
|
||||
### Security Considerations
|
||||
- Secure credential storage
|
||||
- Application password authentication
|
||||
- Data encryption for file transfers
|
||||
- Permission validation
|
||||
- Audit logging for sync operations
|
||||
|
||||
## Success Criteria
|
||||
|
||||
1. Successfully sync all content types between two WordPress instances
|
||||
2. Handle URL rewriting accurately for domain changes
|
||||
3. Support both REST API and file transfer methods
|
||||
4. Provide clear error messages and recovery options
|
||||
5. Work with non-publicly accessible instances
|
||||
6. Function without git or wp-cli dependencies
|
||||
7. Support bidirectional sync with push/pull operations
|
||||
8. Handle custom post types and taxonomies dynamically
|
||||
9. Provide comprehensive admin interface for configuration
|
||||
10. Include robust error handling and logging
|
||||
Reference in New Issue
Block a user