wordpress-agent-kit 0.4.0 → 0.5.1

package/skills-custom/wp-wpengine/scripts/ci-gate.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# ci-gate.sh — run the full CI gate locally before pushing.
+#
+# Mirrors what GitHub Actions ci-gate.yml runs. Use this before any push
+# to a branch that triggers a WP Engine deploy.
+#
+# Usage:
+#   bash scripts/ci-gate.sh              # run both gates
+#   bash scripts/ci-gate.sh --php-only   # PHP gate only
+#   bash scripts/ci-gate.sh --js-only    # JS/TS gate only
+#
+# Exit code: 0 = all passed, 1 = at least one check failed.
+
+set -uo pipefail
+root="$(git rev-parse --show-toplevel)"
+cd "$root"
+
+PHP_ONLY=false
+JS_ONLY=false
+for arg in "$@"; do
+  [[ "$arg" == "--php-only" ]] && PHP_ONLY=true
+  [[ "$arg" == "--js-only" ]] && JS_ONLY=true
+done
+
+PASS=0
+FAIL=0
+
+run() {
+  local label="$1"; shift
+  echo "▶ $label"
+  if "$@" 2>&1; then
+    echo "  ✓ $label"
+    ((PASS++))
+  else
+    echo "  ✗ FAILED: $label"
+    ((FAIL++))
+    return 1
+  fi
+}
+
+# ── PHP gate ──────────────────────────────────────────────────────────────────
+if ! $JS_ONLY; then
+  echo ""
+  echo "── PHP gate ──────────────────────────────────────────────────────────"
+  if command -v composer >/dev/null 2>&1 && [ -f composer.json ]; then
+    if [ ! -d vendor ]; then
+      echo "▶ composer install"
+      composer install --no-interaction --quiet
+    fi
+
+    run "php -l (all tracked PHP files)" \
+      bash -c 'git ls-files "*.php" | xargs -P4 php -l > /dev/null'
+
+    if [ -x vendor/bin/phpcs ]; then
+      run "phpcs (WordPress coding standards)" composer run phpcs
+    else
+      echo "  ⚠  phpcs not found — run: composer install"
+    fi
+
+    if [ -x vendor/bin/phpstan ]; then
+      run "phpstan (static analysis)" composer run phpstan
+    else
+      echo "  ⚠  phpstan not found — run: composer install"
+    fi
+  else
+    echo "  ⚠  composer not available or no composer.json — skipping PHP gate"
+  fi
+fi
+
+# ── JS/TS gate ────────────────────────────────────────────────────────────────
+if ! $PHP_ONLY; then
+  echo ""
+  echo "── JS/TS gate ────────────────────────────────────────────────────────"
+  if [ -f package.json ]; then
+    if [ ! -d node_modules ]; then
+      echo "▶ npm install"
+      npm install --silent
+    fi
+
+    if [ -x node_modules/.bin/biome ]; then
+      run "biome check (lint + format)" npx biome check .
+    else
+      echo "  ⚠  biome not installed — run: npm install"
+    fi
+
+    if npm run typecheck --if-present 2>/dev/null; then
+      ((PASS++))
+    elif command -v tsc >/dev/null 2>&1 || [ -x node_modules/.bin/tsc ]; then
+      run "tsc --noEmit (type check)" npx tsc --noEmit
+    fi
+
+    if npm run test --if-present 2>/dev/null; then
+      ((PASS++))
+    fi
+
+    if npm run build --if-present 2>/dev/null; then
+      ((PASS++))
+    fi
+  else
+    echo "  ⚠  No package.json — skipping JS/TS gate"
+  fi
+fi
+
+# ── Summary ───────────────────────────────────────────────────────────────────
+echo ""
+echo "── CI Gate Result ────────────────────────────────────────────────────"
+echo "  Passed : $PASS"
+echo "  Failed : $FAIL"
+echo ""
+
+if [[ "$FAIL" -eq 0 ]]; then
+  echo "✅ Gate green — safe to push."
+  exit 0
+else
+  echo "❌ Gate failed — fix the issues above before pushing."
+  echo "   --no-verify is not a valid workaround; CI will catch the same failures."
+  exit 1
+fi

package/skills-custom/wp-wpengine/scripts/wpe-check.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# wpe-check.sh — verify SSH connectivity to all configured WP Engine environments.
+#
+# Reads installs from wp-cli.yml @aliases (ssh: field) or from WPE_INSTALLS env var.
+# Useful after first-time machine setup or when debugging SSH issues.
+#
+# Usage:
+#   bash scripts/wpe-check.sh
+#   WPE_INSTALLS="mysite mysitestg mysitedev" bash scripts/wpe-check.sh
+#
+# Exit code: 0 = all connected, 1 = at least one failed.
+
+set -uo pipefail
+root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$root"
+
+SSH_OPTS="-o BatchMode=yes -o ConnectTimeout=8 -o StrictHostKeyChecking=accept-new"
+
+# ── Discover installs from wp-cli.yml @aliases ────────────────────────────────
+declare -A ALIAS_MAP   # install → alias label
+CURRENT_ALIAS=""
+
+if [ -f wp-cli.yml ]; then
+  while IFS= read -r line; do
+    if [[ "$line" =~ ^@([a-zA-Z0-9_-]+): ]]; then
+      CURRENT_ALIAS="${BASH_REMATCH[1]}"
+    elif [[ "$line" =~ ^[[:space:]]+ssh:[[:space:]]+([^@[:space:]]+)@[^[:space:]]+ && -n "$CURRENT_ALIAS" ]]; then
+      INSTALL="${BASH_REMATCH[1]}"
+      ALIAS_MAP["$INSTALL"]="@${CURRENT_ALIAS}"
+      CURRENT_ALIAS=""
+    fi
+  done < wp-cli.yml
+fi
+
+# Fallback: WPE_INSTALLS env var
+if [ "${#ALIAS_MAP[@]}" -eq 0 ] && [ -n "${WPE_INSTALLS:-}" ]; then
+  for slug in $WPE_INSTALLS; do
+    ALIAS_MAP["$slug"]="$slug"
+  done
+fi
+
+if [ "${#ALIAS_MAP[@]}" -eq 0 ]; then
+  echo "No WP Engine installs found."
+  echo ""
+  echo "Options:"
+  echo "  1. Add @aliases with 'ssh: <install>@<install>.ssh.wpengine.net' to wp-cli.yml"
+  echo "  2. Set WPE_INSTALLS='slug1 slug2 slug3' environment variable"
+  exit 1
+fi
+
+echo ""
+echo "── WP Engine SSH connectivity ────────────────────────────────────────"
+printf "  %-25s %-15s %-12s %s\n" "Install" "Alias" "Status" "WP version"
+echo "  ─────────────────────────────────────────────────────────────────"
+
+PASS=0
+FAIL=0
+
+for INSTALL in "${!ALIAS_MAP[@]}"; do
+  ALIAS="${ALIAS_MAP[$INSTALL]}"
+  SSH_HOST="${INSTALL}.ssh.wpengine.net"
+
+  WP_VERSION=$(ssh $SSH_OPTS "${INSTALL}@${SSH_HOST}" \
+    wp core version --skip-plugins --skip-themes 2>/dev/null || echo "")
+
+  if [ -n "$WP_VERSION" ]; then
+    printf "  %-25s %-15s %-12s %s\n" "$INSTALL" "$ALIAS" "✓ connected" "$WP_VERSION"
+    ((PASS++))
+  else
+    printf "  %-25s %-15s %-12s %s\n" "$INSTALL" "$ALIAS" "✗ FAILED" "—"
+    ((FAIL++))
+  fi
+done
+
+echo ""
+echo "  $PASS connected  |  $FAIL failed"
+
+if [[ "$FAIL" -gt 0 ]]; then
+  echo ""
+  echo "Troubleshooting:"
+  echo "  • Confirm key exists:  ls -la ~/.ssh/wpengine_ed25519"
+  echo "  • Confirm permissions: chmod 600 ~/.ssh/wpengine_ed25519"
+  echo "  • Trust the host:      ssh-keyscan -H ssh.wpengine.net >> ~/.ssh/known_hosts"
+  echo "  • Check portal:        https://my.wpengine.com/ssh_keys"
+  echo "  • Verify git access:   ssh git@git.wpengine.com info"
+fi
+
+echo ""
+[[ "$FAIL" -eq 0 ]] && exit 0 || exit 1

package/skills-custom/wp-wpengine/scripts/wpe-preflight.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# wpe-preflight.sh — pre-deploy sanity checks for a WP Engine environment.
+#
+# Verifies SSH access, WP-CLI, site URL consistency, HTTP health, and
+# active plugin count before any deploy touches production or staging.
+#
+# Usage:
+#   INSTALL=mysite bash scripts/wpe-preflight.sh [staging|production]
+#   WPE_INSTALL=mysite bash scripts/wpe-preflight.sh production
+#
+# Exit code: 0 = all checks passed (safe to deploy), 1 = at least one failed.
+
+set -uo pipefail
+
+ENV="${1:-production}"
+INSTALL="${WPE_INSTALL:-${INSTALL:-}}"
+
+if [ -z "$INSTALL" ]; then
+  echo "❌ Usage: INSTALL=<slug> bash scripts/wpe-preflight.sh [staging|production]"
+  echo "   The install slug is the WP Engine environment name (e.g., 'mysite', 'mysitestg')."
+  exit 1
+fi
+
+SSH_HOST="${INSTALL}.ssh.wpengine.net"
+SSH_OPTS="-o BatchMode=yes -o ConnectTimeout=15 -o StrictHostKeyChecking=accept-new"
+WP="ssh $SSH_OPTS ${INSTALL}@${SSH_HOST} wp"
+
+PASS=0
+FAIL=0
+
+check() {
+  local label="$1"; shift
+  printf "  %-50s" "$label"
+  local output
+  if output=$("$@" 2>&1); then
+    echo "✓  $output"
+    ((PASS++))
+  else
+    echo "✗  FAILED"
+    echo "     $output" >&2
+    ((FAIL++))
+  fi
+}
+
+echo ""
+echo "── WP Engine preflight: ${INSTALL} (${ENV}) ─────────────────────"
+echo ""
+
+# ── SSH ───────────────────────────────────────────────────────────────────────
+echo "SSH"
+check "SSH gateway reachable" \
+  ssh $SSH_OPTS "${INSTALL}@${SSH_HOST}" echo "connected"
+
+check "WP-CLI available" \
+  $WP --info --skip-plugins --skip-themes
+
+# ── WordPress ─────────────────────────────────────────────────────────────────
+echo ""
+echo "WordPress"
+check "WP core version" \
+  $WP core version --skip-plugins --skip-themes
+
+check "siteurl option readable" \
+  $WP option get siteurl --skip-plugins --skip-themes
+
+check "Active plugins present (count > 0)" \
+  bash -c "COUNT=\$(${WP} plugin list --status=active --format=count --skip-plugins --skip-themes 2>&1); echo \"\$COUNT active\"; [[ \"\$COUNT\" -gt 0 ]]"
+
+check "No pending DB upgrades" \
+  $WP core update-db --dry-run --skip-plugins --skip-themes
+
+# ── HTTP health ───────────────────────────────────────────────────────────────
+echo ""
+echo "HTTP health"
+SITE_URL=$(ssh $SSH_OPTS "${INSTALL}@${SSH_HOST}" \
+  wp option get home --skip-plugins --skip-themes 2>/dev/null || echo "")
+
+if [ -n "$SITE_URL" ]; then
+  check "Homepage returns 2xx/3xx" \
+    bash -c "STATUS=\$(curl -s -o /dev/null -w '%{http_code}' -L --max-time 15 '${SITE_URL}'); echo \"HTTP \$STATUS\"; [[ \"\$STATUS\" -ge 200 && \"\$STATUS\" -lt 400 ]]"
+
+  check "No PHP errors in homepage body" \
+    bash -c "BODY=\$(curl -sL --max-time 15 '${SITE_URL}'); echo \"\${#BODY} chars\"; ! echo \"\$BODY\" | grep -qi 'fatal error\|parse error\|warning: '"
+
+  check "wp-json REST API responds" \
+    bash -c "STATUS=\$(curl -s -o /dev/null -w '%{http_code}' --max-time 10 '${SITE_URL}/wp-json/wp/v2/'); echo \"HTTP \$STATUS\"; [[ \"\$STATUS\" -ge 200 && \"\$STATUS\" -lt 400 ]]"
+else
+  echo "  ⚠  Could not retrieve site URL — skipping HTTP checks"
+fi
+
+# ── Result ────────────────────────────────────────────────────────────────────
+echo ""
+echo "── Preflight result ──────────────────────────────────────────────────"
+echo "  Passed : $PASS"
+echo "  Failed : $FAIL"
+echo ""
+
+if [[ "$FAIL" -eq 0 ]]; then
+  echo "✅ All checks passed — safe to deploy to ${ENV}."
+  exit 0
+else
+  echo "❌ Preflight failed — resolve the issues above before deploying to ${ENV}."
+  exit 1
+fi

package/.github/workflows/ci.yml

@@ -1,44 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main, master]
-  pull_request:
-    branches: [main, master]
-
-jobs:
-  lint-and-test:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
-          run_install: false
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Check formatting
-        run: pnpm run format:check
-
-      - name: Run lint
-        run: pnpm run lint:check
-
-      - name: Type check
-        run: pnpm run check
-
-      - name: Run tests
-        run: pnpm run test:run
-
-      - name: Build
-        run: pnpm run build

package/.husky/pre-commit

@@ -1,7 +0,0 @@
-#!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
-
-pnpm exec biome check --write .
-git add -A
-pnpm run lint:check
-pnpm run test:run

package/CLI_REVIEW.md

@@ -1,250 +0,0 @@
-# WordPress Agent Kit CLI - Accessibility & Agent-Friendly Review
-
-**Date**: 2026-06-08  
-**Version**: 0.2.1
-
----
-
-## Executive Summary
-
-The current CLI is functional for **human developers** using interactive prompts (`@clack/prompts`), but lacks features for **programmatic/agent usage**:
-
-- ❌ No JSON output mode
-- ❌ No machine-readable result objects
-- ❌ No programmatic API (only CLI entrypoint)
-- ❌ No non-interactive "headless" mode for all commands
-- ❌ No structured logging/event streaming
-- ❌ Exit codes not consistently semantic
-
----
-
-## Current Architecture
-
-```
-src/
-├── cli.ts                    # Entry point, Commander setup
-├── commands/
-│   ├── install.ts           # Non-interactive (args + flags only) ✓
-│   ├── setup.ts             # Interactive (prompts only) ✗
-│   ├── sync-skills.ts       # Non-interactive (args + flags only) ✓
-│   └── run-playground.ts    # Non-interactive ✓
-├── lib/
-│   ├── installer.ts         # Core logic (pure functions) ✓
-│   └── triage-mapper.ts     # Pure mappers ✓
-└── utils/
-    ├── paths.ts             # Path resolution
-    └── run.ts              # Command runner
-```
-
-**Good**: Core logic (`installKit`, mappers) is pure and testable.  
-**Gap**: `setup.ts` couples interactive prompts with business logic.
-
----
-
-## Recommendations
-
-### 1. Add JSON Output Mode (--json)
-
-**Goal**: Every command outputs structured JSON to stdout when requested.
-
-```bash
-# Success
-wp-agent-kit install /path/to/project --platform github --json
-# {"success":true,"targetDir":"/path/to/project","platform":"github","filesCopied":["AGENTS.md",".github/..."],"durationMs":142}
-
-# Failure
-wp-agent-kit install /nonexistent --json
-# {"success":false,"error":"E_NOT_FOUND","message":"Target directory does not exist","code":"ENOENT"}
-```
-
-**Implementation**:
-- Add `--json` / `--output json` global flag in `cli.ts`
-- Create `OutputFormatter` utility: `json`, `human`, `quiet`
-- Return structured result objects from all command actions
-- Separate stdout (JSON) from stderr (human diagnostics)
-
-### 2. Add Machine-Readable Exit Codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | General error |
-| 2 | Invalid arguments / usage |
-| 3 | Target not found / ENOENT |
-| 4 | Permission denied / EACCES |
-| 5 | Already exists (without --force) |
-| 6 | Git/submodule error |
-| 7 | Network/fetch error |
-| 8 | Validation failed |
-| 130 | Cancelled (SIGINT) |
-
-### 3. Extract Programmatic API
-
-Expose core functions for direct import by agents/scripts:
-
-```typescript
-// src/api.ts (new)
-export interface InstallOptions {
-  targetDir: string;
-  platform: Platform;
-  force?: boolean;
-  dryRun?: boolean;
-}
-
-export interface InstallResult {
-  success: boolean;
-  targetDir: string;
-  platform: Platform;
-  filesCreated: string[];
-  filesSkipped: string[];
-  errors: string[];
-  durationMs: number;
-}
-
-export async function installKit(options: InstallOptions): Promise<InstallResult>;
-export async function syncSkills(options: SyncOptions): Promise<SyncResult>;
-export async function runTriage(targetDir: string): Promise<TriageResult>;
-export async function configureAgentsMd(options: ConfigureOptions): Promise<ConfigureResult>;
-```
-
-**Benefits**:
-- Agents can import and call directly: `import { installKit } from 'wordpress-agent-kit'`
-- No subprocess overhead
-- Full TypeScript types
-- Testable in isolation
-
-### 4. Make `setup` Command Headless-Capable
-
-Current `setup.ts` is prompt-driven. Add non-interactive mode:
-
-```bash
-# Full non-interactive (requires all flags)
-wp-agent-kit setup /path/to/project \
-  --project-type plugin \
-  --tech-stack gutenberg,rest-api,composer \
-  --platform github \
-  --yes \
-  --json
-
-# Hybrid: run triage, apply detected values, no prompts
-wp-agent-kit setup /path/to/project --auto --json
-```
-
-**Flag Matrix for `setup`**:
-| Flag | Description |
-|------|-------------|
-| `--project-type <type>` | plugin \| theme \| block-theme \| site \| blocks \| other |
-| `--tech-stack <list>` | Comma-separated: gutenberg,interactivity,rest-api,wpcli,composer,phpstan,npm,playground |
-| `--platform <platform>` | github \| cursor \| claude \| agent \| pi |
-| `--package-manager <pm>` | npm \| pnpm \| yarn |
-| `--auto` | Run triage, apply detected values, skip prompts |
-| `--yes` / `-y` | Accept all confirmations (requires other flags) |
-| `--reset` | Overwrite existing |
-| `--dry-run` | Show what would be done |
-
-### 5. Add Structured Logging / Event Stream
-
-For long-running operations (sync-skills, playground), emit NDJSON events:
-
-```bash
-wp-agent-kit sync-skills --json-stream
-# {"event":"start","phase":"clone","timestamp":"..."}
-# {"event":"progress","phase":"fetch","message":"Fetching tags...","timestamp":"..."}
-# {"event":"complete","phase":"install","result":{"skillsSynced":42,"timestamp":"..."}}
-```
-
-**Events**: `start`, `progress`, `phase-change`, `warning`, `complete`, `error`
-
-### 6. Add Dry-Run / Preview Mode
-
-```bash
-wp-agent-kit install /path --dry-run --json
-# {"wouldCopy":[{"src":"AGENTS.template.md","dest":"/path/AGENTS.md"},{"src":".github/...","dest":"/path/.github/..."}],"wouldCreateDirs":[]}
-
-wp-agent-kit setup /path --dry-run --auto --json
-# {"wouldInstall":true,"detectedType":"plugin","detectedTech":["gutenberg","npm"],"wouldModify":["AGENTS.md"]}
-```
-
-### 7. Add Shell Completion (Modern CLI Standard)
-
-```bash
-# Generate completion scripts
-wp-agent-kit completion bash > /etc/bash_completion.d/wp-agent-kit
-wp-agent-kit completion zsh > ~/.zsh/completions/_wp-agent-kit
-wp-agent-kit completion fish > ~/.config/fish/completions/wp-agent-kit.fish
-```
-
-Commander.js supports this natively: `program.enablePositionalOptions().addHelpCommand().configureOutput({ writeOut: ... })`
-
-### 8. Add `--version` JSON Output
-
-```bash
-wp-agent-kit --version --json
-# {"name":"wp-agent-kit","version":"0.2.1","node":"20.18.0","platform":"linux"}
-```
-
----
-
-## Priority Matrix
-
-| Priority | Feature | Effort | Impact |
-|----------|---------|--------|--------|
-| **P0** | JSON output (`--json`) | Low | High |
-| **P0** | Semantic exit codes | Low | High |
-| **P0** | Programmatic API export | Medium | High |
-| **P1** | Headless `setup` mode | Medium | High |
-| **P1** | Dry-run/preview | Low | Medium |
-| **P2** | NDJSON event streaming | Medium | Medium |
-| **P2** | Shell completions | Low | Medium |
-| **P3** | Man page generation | Low | Low |
-
----
-
-## Example: Agent-Friendly Workflow
-
-```bash
-# 1. Agent detects WordPress project
-wp-agent-kit setup /workspace/my-plugin --auto --json
-# {"success":true,"applied":{"projectType":"plugin","techStack":["gutenberg","npm"]},"filesModified":["AGENTS.md"]}
-
-# 2. Agent syncs latest skills
-wp-agent-kit sync-skills --json
-# {"success":true,"skillsSynced":47,"source":"WordPress/agent-skills@trunk"}
-
-# 3. Agent installs for specific platform (e.g., Cursor)
-wp-agent-kit install /workspace/my-plugin --platform cursor --json
-# {"success":true,"platform":"cursor","targetDir":"/workspace/my-plugin","filesCreated":[".cursor/...","AGENTS.md"]}
-```
-
----
-
-## Implementation Notes
-
-### Minimal Changes for P0
-
-1. **cli.ts**: Add global `--json` flag, result formatter
-2. **commands/*.ts**: Return structured results instead of `process.exit()`
-3. **lib/installer.ts**: Return `InstallResult` object (already close)
-4. **package.json**: Add `"exports": { ".": "./dist/cli.js", "./api": "./dist/api.js" }`
-
-### Testing Strategy
-
-```typescript
-// tests/api/install.api.test.ts
-import { installKit } from '../../src/api.js';
-
-it('returns structured result on success', async () => {
-  const result = await installKit({ targetDir: '/tmp/test', platform: 'github' });
-  expect(result.success).toBe(true);
-  expect(result.filesCreated).toContain('AGENTS.md');
-});
-```
-
----
-
-## References
-
-- [Commander.js JSON output patterns](https://github.com/tj/commander.js/blob/master/Examples/options-json.ts)
-- [CLI Guidelines - Output](https://clig.dev/#output)
-- [12-factor CLI apps](https://medium.com/@jdxcode/12-factor-cli-apps-dd3c227a0e46)
-- [GitHub CLI `gh` JSON patterns](https://cli.github.com/manual/gh_help_formatting)

package/biome.json

@@ -1,39 +0,0 @@
-{
-	"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
-	"vcs": {
-		"enabled": true,
-		"clientKind": "git",
-		"useIgnoreFile": true
-	},
-	"files": {
-		"include": ["src/**/*.ts", "tests/**/*.ts", "scripts/**/*.ts", "extensions/**/*.ts"],
-		"ignoreUnknown": true
-	},
-	"organizeImports": {
-		"enabled": true
-	},
-	"linter": {
-		"enabled": true,
-		"rules": {
-			"recommended": true,
-			"suspicious": {
-				"noExplicitAny": "warn"
-			},
-			"correctness": {
-				"noUnusedVariables": "error"
-			}
-		}
-	},
-	"formatter": {
-		"enabled": true,
-		"indentStyle": "tab",
-		"lineWidth": 100
-	},
-	"javascript": {
-		"formatter": {
-			"quoteStyle": "single",
-			"trailingCommas": "es5",
-			"semicolons": "always"
-		}
-	}
-}