wordpress-agent-kit 0.5.1 → 0.6.0

package/.agents/skills/wp-bootstrap/references/monorepo-patterns.md

@@ -0,0 +1,184 @@
+# WordPress Monorepo Patterns
+
+Common structures agents will encounter. `detect-structure.mjs` identifies them automatically.
+
+---
+
+## Pattern 1 — Single plugin/theme repo (most common)
+
+The repo IS the plugin or theme. `repoRoot === wpPackageDir`.
+
+```
+my-plugin/
+├── my-plugin.php          ← Plugin header here
+├── includes/
+├── assets/src/            ← JS/CSS source (gitignored dist/)
+├── tests/
+├── composer.json          ← plugin-level (Pest tests)
+├── package.json           ← @wordpress/scripts or Biome
+└── .agents/skills/        ← installed by wp-agent-kit
+```
+
+**detect-structure.mjs output:**
+```json
+{
+  "isMonorepo": false,
+  "wpPackages": [{ "type": "plugin", "path": ".", "name": "My Plugin" }],
+  "wpRoot": "."  // or null if Playground-only
+}
+```
+
+**WP Engine deploy:** push the entire repo.
+**Playground:** `--mount=.:/wordpress/wp-content/plugins/my-plugin`
+
+---
+
+## Pattern 2 — wp-agent-os style (WP packages + non-WP packages at root)
+
+Multiple WP packages and JS packages at the top level. No WP core in repo.
+
+```
+project/
+├── wpaos/                 ← companion plugin (Plugin Name: in wpaos.php)
+├── wpaos-blocks/          ← generated plugin (Plugin Name: in wpaos-blocks.php)
+├── wpaos-theme/           ← block theme (Theme Name: in style.css)
+├── design-system/         ← TypeScript/Node (not a WP package)
+├── backend/               ← Firebase/Genkit (not a WP package)
+├── web/                   ← Next.js (not a WP package)
+├── composer.json          ← ROOT: dev tooling only (PHPCS/PHPStan) — NOT shipped
+├── pnpm-workspace.yaml    ← workspace includes design-system, backend, web, tools/e2e
+├── biome.json             ← root JS/TS lint+format
+└── tools/
+    ├── setup.sh           ← one-command bootstrap
+    ├── package-plugins.sh ← build + zip WP packages
+    └── playground/        ← Playground launch + verify scripts
+```
+
+**detect-structure.mjs output:**
+```json
+{
+  "isMonorepo": true,
+  "packageManager": "pnpm",
+  "wpPackages": [
+    { "type": "plugin", "path": "wpaos", "name": "WP Agent OS" },
+    { "type": "plugin", "path": "wpaos-blocks", "name": "WP Agent OS Blocks" },
+    { "type": "theme", "path": "wpaos-theme", "name": "WP Agent OS Theme" }
+  ],
+  "wpRoot": null,
+  "playgroundOnly": true
+}
+```
+
+**WP Engine deploy:** `bash tools/package-plugins.sh` → upload zips. No git push from monorepo.
+**Playground:** mount each WP package separately. See Playground patterns reference.
+
+---
+
+## Pattern 3 — Bedrock / full-stack (WP core in repo)
+
+Roots Bedrock or similar — WP core managed by Composer, web root is a subdirectory.
+
+```
+project/
+├── web/
+│   ├── wp/                ← WP core (managed by Composer)
+│   ├── app/
+│   │   ├── plugins/       ← custom plugins here
+│   │   └── themes/        ← custom themes here
+│   └── wp-config.php
+├── config/
+│   └── environments/
+├── composer.json          ← Bedrock manages WP core + plugins via Composer
+└── .env
+```
+
+**detect-structure.mjs output:**
+```json
+{
+  "wpRoot": "web",
+  "wpPackages": [],  // plugins detected under web/app/plugins/
+  "wpackagist": true  // Bedrock always uses WPackagist
+}
+```
+
+**WP Engine deploy:** push the whole repo OR just the `web/` subtree:
+```bash
+git subtree push --prefix=web wpe-prod main
+```
+**wp-cli.yml:**
+```yaml
+path: ./web
+@production:
+  ssh: <install>@<install>.ssh.wpengine.net
+  path: /home/wpe-user/sites/<install>
+```
+
+---
+
+## Pattern 4 — Agency monorepo (multiple client sites)
+
+```
+agency-repo/
+├── client-a/
+│   ├── plugins/my-plugin/
+│   └── themes/my-theme/
+├── client-b/
+│   └── plugins/client-b-plugin/
+└── shared/
+    └── components/        ← shared JS library
+```
+
+Not well-suited for a single wp-agent-kit install. Better to:
+- Install wp-agent-kit per client: `wp-agent-kit install ./client-a`
+- Or: one install at root with per-client `wp-cli.yml` aliases
+
+---
+
+## Key questions for each structure
+
+1. **Is WP core in this repo?** (`wpRoot` not null)
+   - Yes → use `--path` in WP-CLI, `wp-cli.yml` `path:` at that location
+   - No → Playground-only local dev, deploy via zip or separate deploy repo
+
+2. **Are plugins/themes installed into a WP install, or are they standalone packages?**
+   - Standalone → Playground mounts, zip deploy, WPackagist for dependencies
+   - In a WP install → `wp plugin install`, WP-CLI, Bedrock patterns
+
+3. **How many WP packages?**
+   - 1 → push the whole repo to WP Engine
+   - 2+ → package individually, upload each as a zip; OR subtree push
+
+4. **Is there a build step?**
+   - Yes (JS assets, generated plugins) → CI must build before deploying
+   - No → push source files directly
+
+---
+
+## wp-bootstrap.config.json — optional config file
+
+Place at repo root to override detection:
+
+```json
+{
+  "packageManager": "pnpm",
+  "jsWorkspaces": ["design-system", "backend", "web", "tools/e2e"],
+  "phpDirs": [".", "wpaos"],
+  "hooksDir": ".githooks",
+  "buildCommand": "cd design-system && pnpm run build && pnpm run build:blocks",
+  "wpPackages": [
+    { "path": "wpaos",        "type": "plugin", "slug": "wpaos",        "mainFile": "wpaos.php" },
+    { "path": "wpaos-blocks", "type": "plugin", "slug": "wpaos-blocks", "mainFile": "wpaos-blocks.php" },
+    { "path": "wpaos-theme",  "type": "theme",  "slug": "wpaos-theme" }
+  ],
+  "playgroundMounts": [
+    "./wpaos:/wordpress/wp-content/plugins/wpaos",
+    "./wpaos-blocks:/wordpress/wp-content/plugins/wpaos-blocks",
+    "./wpaos-theme:/wordpress/wp-content/themes/wpaos-theme"
+  ],
+  "wpeEnvironments": {
+    "production": { "install": "mysite",    "gitUrl": "git@git.wpengine.com:mysite.git" },
+    "staging":    { "install": "mysitestg", "gitUrl": "git@git.wpengine.com:mysitestg.git" },
+    "development":{ "install": "mysitedev", "gitUrl": "git@git.wpengine.com:mysitedev.git" }
+  }
+}
+```

package/.agents/skills/wp-bootstrap/scripts/bootstrap.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+# bootstrap.sh — one-command dev setup for a WordPress project or monorepo.
+#
+# Generalized from the wp-agent-os tools/setup.sh pattern. Idempotent: safe
+# to re-run on an existing clone. Activates git hooks, installs PHP and JS
+# dependencies, and verifies the environment.
+#
+# Usage:
+#   bash .agents/skills/wp-bootstrap/scripts/bootstrap.sh [OPTIONS]
+#
+# Options:
+#   --php-only     Skip JS workspace installs
+#   --js-only      Skip PHP/Composer installs
+#   --no-hooks     Skip git hook activation
+#   --quiet        Minimal output
+#
+# Reads wp-bootstrap.config.json from repo root if present:
+#   {
+#     "packageManager": "pnpm",
+#     "jsWorkspaces": ["design-system", "backend", "web", "tools/e2e"],
+#     "phpDirs": [".", "wpaos"],
+#     "hooksDir": ".githooks"
+#   }
+
+set -uo pipefail
+root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$root"
+
+PHP_ONLY=false; JS_ONLY=false; NO_HOOKS=false; QUIET=false
+for arg in "$@"; do
+  case "$arg" in
+    --php-only) PHP_ONLY=true ;;
+    --js-only)  JS_ONLY=true ;;
+    --no-hooks) NO_HOOKS=true ;;
+    --quiet)    QUIET=true ;;
+  esac
+done
+
+OK=0; WARN=0
+say()  { $QUIET || printf '\n\033[1m→ %s\033[0m\n' "$*"; }
+good() { $QUIET || printf '  \033[32m✓\033[0m %s\n' "$*"; ((OK++)); }
+nope() { printf '  \033[33m⚠\033[0m %s\n' "$*" >&2; ((WARN++)); }
+
+# ── Read optional config ──────────────────────────────────────────────────────
+CONFIG_FILE="$root/wp-bootstrap.config.json"
+if [ -f "$CONFIG_FILE" ] && command -v node >/dev/null 2>&1; then
+  PKG_MGR=$(node -e "process.stdout.write(require('$CONFIG_FILE').packageManager ?? '')")
+  HOOKS_DIR=$(node -e "process.stdout.write(require('$CONFIG_FILE').hooksDir ?? '.githooks')")
+  JS_WS=$(node -e "console.log((require('$CONFIG_FILE').jsWorkspaces ?? []).join('\n'))")
+  PHP_DIRS=$(node -e "console.log((require('$CONFIG_FILE').phpDirs ?? ['.']).join('\n'))")
+else
+  # Auto-detect
+  if [ -f "pnpm-lock.yaml" ] || [ -f "pnpm-workspace.yaml" ]; then PKG_MGR="pnpm"
+  elif [ -f "yarn.lock" ]; then PKG_MGR="yarn"
+  else PKG_MGR="npm"; fi
+
+  HOOKS_DIR=".githooks"
+  [ -d ".husky" ] && HOOKS_DIR=".husky"
+
+  # Discover JS workspaces from pnpm-workspace.yaml
+  if [ -f "pnpm-workspace.yaml" ] && command -v node >/dev/null 2>&1; then
+    JS_WS=$(node -e "
+      const fs = require('fs');
+      const yaml = fs.readFileSync('pnpm-workspace.yaml','utf-8');
+      const pkgs = [...yaml.matchAll(/[-]\\s+['\"]?([^'\"#\\n]+)['\"]?/g)].map(m=>m[1].trim().replace(/\/\*\$/,''));
+      pkgs.filter(p=>fs.existsSync(p)).forEach(p=>console.log(p));
+    " 2>/dev/null || echo "")
+  else
+    JS_WS=""
+  fi
+
+  # Discover PHP dirs (any dir with its own composer.json)
+  PHP_DIRS="."
+  while IFS= read -r -d '' composer_file; do
+    dir="$(dirname "${composer_file#./}")"
+    [ "$dir" != "." ] && PHP_DIRS="$PHP_DIRS
+$dir"
+  done < <(find . -maxdepth 3 -name "composer.json" \
+    -not -path "*/vendor/*" -not -path "*/node_modules/*" -print0)
+fi
+
+# ── 1. Git hooks ──────────────────────────────────────────────────────────────
+if ! $NO_HOOKS; then
+  say "Activating git hooks (${HOOKS_DIR}/)"
+  if git rev-parse --git-dir >/dev/null 2>&1; then
+    if [ -d "$HOOKS_DIR" ]; then
+      git config core.hooksPath "$HOOKS_DIR"
+      chmod +x "$HOOKS_DIR"/* 2>/dev/null || true
+      good "core.hooksPath = $HOOKS_DIR ($(ls "$HOOKS_DIR" | grep -v README | tr '\n' ' '))"
+    else
+      nope "$HOOKS_DIR not found — create it and add a pre-push script"
+    fi
+  else
+    nope "Not a git repo — skipping hook activation"
+  fi
+fi
+
+# ── 2. PHP dependencies ───────────────────────────────────────────────────────
+if ! $JS_ONLY && command -v composer >/dev/null 2>&1; then
+  while IFS= read -r php_dir; do
+    [ -z "$php_dir" ] && continue
+    [ ! -f "$root/$php_dir/composer.json" ] && continue
+    say "Composer install ($php_dir)"
+    if ( cd "$root/$php_dir" && composer install --no-interaction --quiet ); then
+      good "$php_dir: composer deps installed"
+    else
+      nope "$php_dir: composer install failed"
+    fi
+  done <<< "$PHP_DIRS"
+elif ! $JS_ONLY; then
+  nope "composer not found — install Composer (https://getcomposer.org), then re-run"
+fi
+
+# ── 3. JS dependencies ────────────────────────────────────────────────────────
+if ! $PHP_ONLY; then
+  if ! command -v "$PKG_MGR" >/dev/null 2>&1; then
+    nope "$PKG_MGR not found — install it, then re-run"
+  else
+    # Root package.json first
+    if [ -f "$root/package.json" ]; then
+      say "JS install root ($PKG_MGR)"
+      if ( cd "$root" && "$PKG_MGR" install --silent 2>/dev/null || "$PKG_MGR" install ); then
+        good "root: JS deps installed"
+      else
+        nope "root: $PKG_MGR install failed"
+      fi
+    fi
+
+    # Workspaces (if not handled by root install)
+    if [ -n "$JS_WS" ] && [ "$PKG_MGR" = "npm" ]; then
+      while IFS= read -r ws; do
+        [ -z "$ws" ] && continue
+        [ ! -f "$root/$ws/package.json" ] && continue
+        say "JS install $ws"
+        if ( cd "$root/$ws" && npm install --silent ); then
+          good "$ws: npm deps installed"
+        else
+          nope "$ws: npm install failed"
+        fi
+      done <<< "$JS_WS"
+    fi
+  fi
+fi
+
+# ── 4. Summary ────────────────────────────────────────────────────────────────
+say "Bootstrap complete"
+echo "  PHP gate:  composer fix && composer phpcs && composer phpstan"
+echo "  JS gate:   ${PKG_MGR} run lint && ${PKG_MGR} test"
+echo "  Full gate: ${PKG_MGR} run gate (if configured)"
+[ "$WARN" -gt 0 ] && echo "  ⚠  $WARN warning(s) above — fix them, then re-run."
+exit 0