claude-plugin-wordpress-manager 1.8.0 → 2.0.0

package/skills/wp-cicd/references/bitbucket-pipelines-wordpress.md

@@ -0,0 +1,142 @@
+# Bitbucket Pipelines for WordPress
+
+Step-based pipeline configuration for WordPress projects hosted on Bitbucket.
+
+## Full Pipeline Template
+
+```yaml
+image: php:8.2-cli
+
+definitions:
+  caches:
+    composer: ~/.composer/cache
+  services:
+    mysql:
+      image: mysql:8.0
+      variables:
+        MYSQL_ROOT_PASSWORD: root
+        MYSQL_DATABASE: wordpress_tests
+    docker:
+      memory: 2048
+
+pipelines:
+  default:
+    - parallel:
+        - step:
+            name: PHPCS Lint
+            caches:
+              - composer
+            script:
+              - apt-get update && apt-get install -y unzip git
+              - curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
+              - composer global require --dev wp-coding-standards/wpcs:"^3.0"
+              - composer global exec phpcs -- --config-set installed_paths $(composer global config home)/vendor/wp-coding-standards/wpcs
+              - composer global exec phpcs -- --standard=WordPress .
+
+        - step:
+            name: PHPStan
+            caches:
+              - composer
+            script:
+              - apt-get update && apt-get install -y unzip git
+              - curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
+              - composer install --no-interaction --prefer-dist
+              - vendor/bin/phpstan analyse
+
+    - parallel:
+        - step:
+            name: PHPUnit
+            caches:
+              - composer
+            services:
+              - mysql
+            script:
+              - apt-get update && apt-get install -y unzip git default-mysql-client
+              - docker-php-ext-install mysqli
+              - curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
+              - composer install --no-interaction --prefer-dist
+              - bash bin/install-wp-tests.sh wordpress_tests root root 127.0.0.1 latest
+              - vendor/bin/phpunit
+
+        - step:
+            name: Jest Unit Tests
+            image: node:20
+            caches:
+              - node
+            script:
+              - npm ci
+              - npx wp-scripts test-unit-js --coverage
+
+    - step:
+        name: E2E Tests
+        image: node:20
+        size: 2x
+        services:
+          - docker
+        caches:
+          - node
+        script:
+          - npm ci
+          - npm run build
+          - npx wp-env start
+          - npx playwright install chromium --with-deps
+          - npx playwright test
+        artifacts:
+          - playwright-report/**
+
+  branches:
+    main:
+      - parallel:
+          - step:
+              name: PHPCS Lint
+              caches:
+                - composer
+              script:
+                - apt-get update && apt-get install -y unzip git
+                - curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
+                - composer global require --dev wp-coding-standards/wpcs:"^3.0"
+                - composer global exec phpcs -- --config-set installed_paths $(composer global config home)/vendor/wp-coding-standards/wpcs
+                - composer global exec phpcs -- --standard=WordPress .
+          - step:
+              name: PHPStan
+              caches:
+                - composer
+              script:
+                - apt-get update && apt-get install -y unzip git
+                - curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
+                - composer install --no-interaction --prefer-dist
+                - vendor/bin/phpstan analyse
+      - step:
+          name: Deploy to Production
+          deployment: production
+          trigger: manual
+          script:
+            - pipe: atlassian/ssh-run:0.8.1
+              variables:
+                SSH_USER: $SSH_USER
+                SERVER: $SSH_HOST
+                COMMAND: |
+                  cd /var/www/html/wp-content/plugins/my-plugin
+                  git pull origin main
+                  composer install --no-dev --no-interaction
+                  wp cache flush
+```
+
+## Repository Variables
+
+Set in Repository Settings > Pipelines > Repository variables:
+
+| Variable | Secured |
+|----------|---------|
+| `SSH_USER` | No |
+| `SSH_HOST` | No |
+| `SSH_PRIVATE_KEY` | Yes |
+
+## Tips
+
+- Use `parallel` keyword for concurrent steps (lint + static analysis)
+- Use `size: 2x` for memory-intensive steps like E2E with Docker
+- Use `trigger: manual` for production deployment approval
+- Use `deployment: production` to track deploy history
+- Use Bitbucket Pipes for common tasks (SSH, S3, Slack notifications)
+- Bitbucket has a 120-minute timeout per step — watch for slow E2E suites

package/skills/wp-cicd/references/deploy-strategies.md

@@ -0,0 +1,164 @@
+# Deployment Strategies for WordPress
+
+Strategies for deploying WordPress plugins, themes, and full sites via CI/CD pipelines. Each strategy balances risk, downtime, and complexity.
+
+## Direct Push
+
+Simplest strategy — deploy directly to the server.
+
+```bash
+# Via SSH
+ssh deploy@server "cd /var/www/html/wp-content/plugins/my-plugin && git pull origin main"
+
+# Via rsync
+rsync -avz --delete --exclude='.git' --exclude='node_modules' ./ deploy@server:/path/to/plugin/
+```
+
+**Pros:** Simple, fast, no extra infrastructure.
+**Cons:** No rollback, brief downtime during deploy, risk of partial deploy.
+**Use when:** Development/staging, low-traffic sites.
+
+## Blue-Green Deployment
+
+Maintain two identical environments. Deploy to inactive, then swap.
+
+```
+1. Deploy to GREEN (inactive)
+2. Run smoke tests on GREEN
+3. Swap router: GREEN → active, BLUE → inactive
+4. If issues: swap back instantly
+```
+
+WordPress implementation:
+```bash
+# Deploy to staging directory
+rsync -avz ./ deploy@server:/var/www/green/wp-content/plugins/my-plugin/
+
+# Run smoke tests
+curl -f https://green.example.com/wp-json/ || exit 1
+
+# Swap symlink
+ssh deploy@server "ln -sfn /var/www/green /var/www/html"
+
+# Flush caches
+ssh deploy@server "cd /var/www/html && wp cache flush && wp rewrite flush"
+```
+
+**Pros:** Zero downtime, instant rollback.
+**Cons:** Requires double infrastructure, database must be shared.
+**Use when:** Production with uptime requirements.
+
+## Rolling Deployment
+
+Deploy one server at a time behind a load balancer.
+
+```
+1. Remove server-1 from load balancer
+2. Deploy to server-1
+3. Healthcheck server-1
+4. Add server-1 back to load balancer
+5. Repeat for server-2, server-3...
+```
+
+**Pros:** Zero downtime, gradual rollout.
+**Cons:** Requires load balancer, mixed versions briefly.
+**Use when:** Multi-server setups.
+
+## Canary Deployment
+
+Deploy to a small percentage of traffic first.
+
+```
+1. Deploy to canary server (5% traffic)
+2. Monitor error rates and performance
+3. If healthy: roll out to remaining 95%
+4. If issues: route all traffic away from canary
+```
+
+**Pros:** Lowest risk, real-world validation.
+**Cons:** Requires traffic routing infrastructure.
+**Use when:** High-traffic production, risky changes.
+
+## Manual Approval Gate
+
+CI runs all tests, then waits for human approval before deploying.
+
+GitHub Actions:
+```yaml
+deploy:
+  needs: [test]
+  environment: production  # Requires manual approval in GitHub settings
+  steps:
+    - run: ./deploy.sh
+```
+
+GitLab CI:
+```yaml
+deploy:
+  when: manual
+  environment:
+    name: production
+```
+
+**Pros:** Human review before production.
+**Cons:** Adds latency to deploy cycle.
+**Use when:** Always recommended for production.
+
+## WordPress-Specific Considerations
+
+### Maintenance Mode
+
+For deploys that change database schema or run migrations:
+
+```bash
+# Enable maintenance mode
+ssh deploy@server "cd /var/www/html && wp maintenance-mode activate"
+
+# Deploy
+rsync -avz ./ deploy@server:/var/www/html/wp-content/plugins/my-plugin/
+
+# Run migrations (if any)
+ssh deploy@server "cd /var/www/html && wp plugin activate my-plugin"
+
+# Disable maintenance mode
+ssh deploy@server "cd /var/www/html && wp maintenance-mode deactivate"
+```
+
+### Post-Deploy Cache Flush
+
+Always flush caches after deployment:
+
+```bash
+wp cache flush                    # Object cache
+wp rewrite flush                  # Permalink rewrite rules
+wp transient delete --all         # Transients
+```
+
+If using a caching plugin (WP Super Cache, W3 Total Cache):
+```bash
+wp w3-total-cache flush all       # W3TC
+wp super-cache flush              # WP Super Cache
+```
+
+### Database Migrations
+
+For plugins with custom tables:
+```bash
+# Before deploy: backup
+wp db export pre-deploy-backup.sql
+
+# After deploy: run activation hooks that create/update tables
+wp plugin deactivate my-plugin && wp plugin activate my-plugin
+```
+
+## Choosing a Strategy
+
+| Factor | Direct Push | Blue-Green | Rolling | Canary |
+|--------|------------|------------|---------|--------|
+| Downtime | Brief | Zero | Zero | Zero |
+| Rollback speed | Slow | Instant | Medium | Fast |
+| Infrastructure cost | Low | 2x | Same | Same + routing |
+| Complexity | Low | Medium | High | High |
+| Risk | High | Low | Medium | Low |
+
+**Recommendation:** Start with Direct Push + Manual Approval for staging. Move to Blue-Green for production when uptime matters.

package/skills/wp-cicd/references/github-actions-wordpress.md

@@ -0,0 +1,183 @@
+# GitHub Actions for WordPress
+
+Complete workflow templates for WordPress plugin and theme CI/CD pipelines.
+
+## Full Pipeline Template
+
+```yaml
+name: WordPress CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+          tools: cs2pr, phpcs
+      - name: Install PHPCS standards
+        run: |
+          composer global require --dev wp-coding-standards/wpcs:"^3.0"
+          phpcs --config-set installed_paths $(composer global config home)/vendor/wp-coding-standards/wpcs
+      - name: Run PHPCS
+        run: phpcs --standard=WordPress --report=checkstyle . | cs2pr
+
+  static-analysis:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+      - name: Install dependencies
+        run: composer install --no-interaction --prefer-dist
+      - name: Run PHPStan
+        run: vendor/bin/phpstan analyse --error-format=github
+
+  test-php:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        php: ['7.4', '8.0', '8.2', '8.3']
+        wp: ['latest']
+        include:
+          - php: '8.2'
+            wp: 'nightly'
+      fail-fast: false
+    services:
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_ROOT_PASSWORD: root
+          MYSQL_DATABASE: wordpress_tests
+        ports: ['3306:3306']
+        options: >-
+          --health-cmd="mysqladmin ping"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=3
+    steps:
+      - uses: actions/checkout@v4
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: mysqli
+          coverage: xdebug
+      - name: Install WP Test Suite
+        run: bash bin/install-wp-tests.sh wordpress_tests root root 127.0.0.1 ${{ matrix.wp }}
+      - name: Install dependencies
+        run: composer install --no-interaction --prefer-dist
+      - name: Run PHPUnit
+        run: vendor/bin/phpunit --coverage-clover=coverage.xml
+      - name: Upload coverage
+        if: matrix.php == '8.2' && matrix.wp == 'latest'
+        uses: codecov/codecov-action@v4
+        with:
+          file: coverage.xml
+
+  test-e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci
+      - name: Build
+        run: npm run build
+      - name: Start wp-env
+        run: npx wp-env start
+      - name: Install Playwright browsers
+        run: npx playwright install chromium --with-deps
+      - name: Run E2E tests
+        run: npx playwright test
+      - name: Upload artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 7
+
+  test-js:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci
+      - name: Run Jest
+        run: npx wp-scripts test-unit-js --coverage
+
+  deploy:
+    needs: [lint, static-analysis, test-php, test-e2e, test-js]
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - uses: actions/checkout@v4
+      - name: Deploy via SSH
+        uses: appleboy/ssh-action@v1
+        with:
+          host: ${{ secrets.SSH_HOST }}
+          username: ${{ secrets.SSH_USER }}
+          key: ${{ secrets.SSH_PRIVATE_KEY }}
+          script: |
+            cd /var/www/html/wp-content/plugins/my-plugin
+            git pull origin main
+            composer install --no-dev --no-interaction
+            wp cache flush
+```
+
+## Caching Strategies
+
+```yaml
+# Composer cache
+- name: Get Composer cache dir
+  id: composer-cache
+  run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+- uses: actions/cache@v4
+  with:
+    path: ${{ steps.composer-cache.outputs.dir }}
+    key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+
+# npm cache (handled by setup-node cache: 'npm')
+
+# wp-env Docker image cache
+- name: Cache Docker images
+  uses: ScribeMD/docker-cache@0.5.0
+  with:
+    key: docker-${{ runner.os }}-${{ hashFiles('.wp-env.json') }}
+```
+
+## Required Status Checks
+
+Configure in repository Settings > Branches > Branch protection:
+
+1. Require status checks: `lint`, `static-analysis`, `test-php`, `test-e2e`
+2. Require branches to be up to date
+3. Require pull request reviews before merging
+
+## Tips
+
+- Use `concurrency` to cancel superseded runs on the same branch
+- Use `fail-fast: false` in matrix to see all failures, not just the first
+- Upload Playwright reports as artifacts for debugging
+- Use GitHub Environments for deploy approval gates
+- Cache Docker images for wp-env to speed up E2E jobs

package/skills/wp-cicd/references/gitlab-ci-wordpress.md

@@ -0,0 +1,189 @@
+# GitLab CI for WordPress
+
+Multi-stage pipeline configuration for WordPress plugin and theme projects on GitLab.
+
+## Full Pipeline Template
+
+```yaml
+stages:
+  - lint
+  - test
+  - build
+  - deploy
+
+variables:
+  MYSQL_ROOT_PASSWORD: root
+  MYSQL_DATABASE: wordpress_tests
+  WP_VERSION: latest
+  PHP_VERSION: "8.2"
+
+# Cache Composer and npm dependencies
+cache:
+  paths:
+    - vendor/
+    - node_modules/
+    - .npm/
+
+# ---------------------------------------------------------------------------
+# Lint stage
+# ---------------------------------------------------------------------------
+
+phpcs:
+  stage: lint
+  image: php:${PHP_VERSION}-cli
+  before_script:
+    - apt-get update && apt-get install -y unzip git
+    - curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
+    - composer global require --dev wp-coding-standards/wpcs:"^3.0"
+    - composer global exec phpcs -- --config-set installed_paths $(composer global config home)/vendor/wp-coding-standards/wpcs
+  script:
+    - composer global exec phpcs -- --standard=WordPress .
+  allow_failure: false
+
+# ---------------------------------------------------------------------------
+# Test stage
+# ---------------------------------------------------------------------------
+
+phpstan:
+  stage: test
+  image: php:${PHP_VERSION}-cli
+  before_script:
+    - apt-get update && apt-get install -y unzip git
+    - curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
+    - composer install --no-interaction --prefer-dist
+  script:
+    - vendor/bin/phpstan analyse
+
+phpunit:
+  stage: test
+  image: php:${PHP_VERSION}-cli
+  services:
+    - name: mysql:8.0
+      alias: mysql
+  variables:
+    MYSQL_HOST: mysql
+  before_script:
+    - apt-get update && apt-get install -y unzip git default-mysql-client
+    - docker-php-ext-install mysqli
+    - curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
+    - composer install --no-interaction --prefer-dist
+    - bash bin/install-wp-tests.sh ${MYSQL_DATABASE} root ${MYSQL_ROOT_PASSWORD} mysql ${WP_VERSION}
+  script:
+    - vendor/bin/phpunit --coverage-text
+  parallel:
+    matrix:
+      - PHP_VERSION: ['7.4', '8.0', '8.2', '8.3']
+
+jest:
+  stage: test
+  image: node:20
+  before_script:
+    - npm ci --cache .npm --prefer-offline
+  script:
+    - npx wp-scripts test-unit-js --coverage
+
+e2e:
+  stage: test
+  image: node:20
+  services:
+    - name: docker:dind
+      alias: docker
+  variables:
+    DOCKER_HOST: tcp://docker:2376
+    DOCKER_TLS_CERTDIR: "/certs"
+  before_script:
+    - npm ci --cache .npm --prefer-offline
+    - npm run build
+    - npx wp-env start
+    - npx playwright install chromium --with-deps
+  script:
+    - npx playwright test
+  artifacts:
+    when: on_failure
+    paths:
+      - playwright-report/
+    expire_in: 7 days
+
+# ---------------------------------------------------------------------------
+# Build stage
+# ---------------------------------------------------------------------------
+
+build:
+  stage: build
+  image: node:20
+  before_script:
+    - npm ci --cache .npm --prefer-offline
+  script:
+    - npm run build
+  artifacts:
+    paths:
+      - build/
+    expire_in: 1 hour
+  only:
+    - main
+    - tags
+
+# ---------------------------------------------------------------------------
+# Deploy stage
+# ---------------------------------------------------------------------------
+
+deploy_staging:
+  stage: deploy
+  image: alpine:latest
+  environment:
+    name: staging
+    url: https://staging.example.com
+  before_script:
+    - apk add --no-cache openssh-client rsync
+    - eval $(ssh-agent -s)
+    - echo "$SSH_PRIVATE_KEY" | ssh-add -
+    - mkdir -p ~/.ssh && chmod 700 ~/.ssh
+    - echo "$SSH_KNOWN_HOSTS" >> ~/.ssh/known_hosts
+  script:
+    - rsync -avz --delete --exclude='.git' ./ $SSH_USER@$SSH_HOST:/var/www/staging/wp-content/plugins/my-plugin/
+    - ssh $SSH_USER@$SSH_HOST "cd /var/www/staging && wp cache flush"
+  only:
+    - develop
+  dependencies:
+    - build
+
+deploy_production:
+  stage: deploy
+  image: alpine:latest
+  environment:
+    name: production
+    url: https://example.com
+  when: manual
+  before_script:
+    - apk add --no-cache openssh-client rsync
+    - eval $(ssh-agent -s)
+    - echo "$SSH_PRIVATE_KEY" | ssh-add -
+    - mkdir -p ~/.ssh && chmod 700 ~/.ssh
+    - echo "$SSH_KNOWN_HOSTS" >> ~/.ssh/known_hosts
+  script:
+    - rsync -avz --delete --exclude='.git' ./ $SSH_USER@$SSH_HOST:/var/www/html/wp-content/plugins/my-plugin/
+    - ssh $SSH_USER@$SSH_HOST "cd /var/www/html && wp cache flush && wp rewrite flush"
+  only:
+    - main
+  dependencies:
+    - build
+```
+
+## GitLab CI/CD Variables
+
+Set in Settings > CI/CD > Variables:
+
+| Variable | Type | Protected | Masked |
+|----------|------|-----------|--------|
+| `SSH_PRIVATE_KEY` | Variable | Yes | Yes |
+| `SSH_KNOWN_HOSTS` | Variable | Yes | No |
+| `SSH_USER` | Variable | Yes | No |
+| `SSH_HOST` | Variable | Yes | No |
+
+## Tips
+
+- Use `parallel: matrix` for PHP version matrix testing
+- Use `when: manual` for production deploy (approval gate)
+- Use `dependencies` to pass artifacts between stages
+- Use Docker-in-Docker service for wp-env in E2E tests
+- Set `allow_failure: true` on nightly WP version tests