wordpress-agent-kit 0.2.2 → 0.3.2

package/extensions/wp-agent-kit/index.ts

@@ -0,0 +1,452 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * WordPress Agent Kit — Pi Extension
+ *
+ * Provides Pi Coding Agent with WordPress development tools:
+ * - 17 WordPress agent skills (plugin/theme/block dev, REST API, WP-CLI, etc.)
+ * - Project triage detection
+ * - Skill installation, syncing, and upgrade management
+ *
+ * Follows Pi Coding Agent SDK conventions (extensions.md, packages.md, skills.md).
+ */
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
+
+// Resolve the API import dynamically — works in both dev (src/) and npm (dist/)
+let apiModule: typeof import('../../dist/lib/api.js');
+try {
+	apiModule = await import('../../dist/lib/api.js');
+} catch {
+	// Fallback for dev: import from source via jiti
+	apiModule = (await import('../../src/lib/api.js')) as typeof import('../../dist/lib/api.js');
+}
+
+const { installKitApi, syncSkillsApi, runTriageApi, isKitInstalled, loadManifest } = apiModule;
+
+export default function (pi: ExtensionAPI) {
+	// =========================================================================
+	// Skills Registration
+	// =========================================================================
+	pi.on('resources_discover', async (_event, _ctx) => {
+		const skillsDir = path.join(PACKAGE_ROOT, '.github', 'skills');
+		const promptsDir = path.join(PACKAGE_ROOT, '.github', 'prompts');
+		return {
+			skillPaths: [skillsDir],
+			promptPaths: [promptsDir],
+		};
+	});
+
+	// =========================================================================
+	// Session notifications
+	// =========================================================================
+	pi.on('session_start', async (_event, ctx) => {
+		const platforms: Array<'pi' | 'github'> = ['pi', 'github'];
+		for (const p of platforms) {
+			if (isKitInstalled(ctx.cwd, p)) {
+				const manifest = loadManifest(ctx.cwd, p);
+				if (manifest) {
+					ctx.ui.setStatus('wp-agent-kit', `WP Agent Kit v${manifest.version}`);
+				}
+				break;
+			}
+		}
+	});
+
+	// =========================================================================
+	// Custom Tools
+	// =========================================================================
+
+	// --- wp_triage ---
+	pi.registerTool({
+		name: 'wp_triage',
+		label: 'WP Triage',
+		description:
+			'Detect WordPress project type (plugin, theme, block theme, site, Gutenberg), signals (block.json, Interactivity API, WP-CLI, REST API), and tooling (PHP/Node). Use before making changes to any WordPress project.',
+		promptSnippet: 'Detect WordPress project type, signals, and tooling',
+		promptGuidelines: [
+			'Use wp_triage before making changes to any WordPress project to understand the codebase.',
+			'Use wp_triage output to route to the correct WordPress development skill.',
+		],
+		parameters: Type.Object({
+			targetDir: Type.Optional(
+				Type.String({
+					description: 'WordPress project directory (defaults to current working directory)',
+				})
+			),
+		}),
+		async execute(_callId, params, _signal, _onUpdate, _ctx) {
+			const targetDir = params.targetDir || process.cwd();
+			const result = await runTriageApi({
+				targetDir,
+				platform: 'pi',
+			});
+
+			if (!result.success) {
+				return {
+					content: [
+						{
+							type: 'text',
+							text: `Triage failed: ${result.error?.message || 'Unknown error'}`,
+						},
+					],
+					details: { error: result.error },
+					isError: true,
+				};
+			}
+
+			const t = result.data;
+			return {
+				content: [
+					{
+						type: 'text',
+						text: JSON.stringify(
+							{
+								project: t.project,
+								signals: t.signals,
+								tooling: t.tooling,
+								recommendation: t.project
+									? `${t.project.primary} project (confidence: ${t.project.confidence}). Use the matching wp-* skill.`
+									: 'Could not determine project type. Review signals manually.',
+							},
+							null,
+							2
+						),
+					},
+				],
+				details: t,
+			};
+		},
+	});
+
+	// --- wp_install_kit ---
+	pi.registerTool({
+		name: 'wp_install_kit',
+		label: 'WP Install Kit',
+		description:
+			'Install WordPress Agent Kit into a project directory. Copies 17 WordPress development skills, agent definitions, workflow instructions, and an AGENTS.md template. Safe by default — preserves user modifications on re-run.',
+		promptSnippet: 'Install WordPress AI agent skills and configuration into a project',
+		promptGuidelines: [
+			'Use wp_install_kit when setting up a new WordPress project for AI agent development.',
+			'Use wp_install_kit with dryRun: true to preview changes before applying.',
+		],
+		parameters: Type.Object({
+			targetDir: Type.String({
+				description: 'WordPress project root directory to install into',
+			}),
+			dryRun: Type.Optional(
+				Type.Boolean({
+					description: 'Preview changes without applying (default: false)',
+				})
+			),
+			force: Type.Optional(
+				Type.Boolean({
+					description: 'Overwrite user modifications on update (default: false)',
+				})
+			),
+		}),
+		async execute(_callId, params, _signal, onUpdate, _ctx) {
+			const opts = {
+				targetDir: params.targetDir,
+				platform: 'pi' as const,
+				dryRun: params.dryRun ?? false,
+				force: params.force ?? false,
+				safe: !(params.force ?? false),
+				backup: true,
+			};
+
+			if (opts.dryRun) {
+				onUpdate?.({ content: [{ type: 'text', text: 'Computing changes (dry-run)...' }] });
+			}
+
+			const result = await installKitApi(opts);
+
+			if (!result.success) {
+				return {
+					content: [
+						{ type: 'text', text: `Install failed: ${result.error?.message || 'Unknown error'}` },
+					],
+					isError: true,
+				};
+			}
+
+			// Dry-run: show change preview
+			if (opts.dryRun && 'wouldExecute' in (result.data || {})) {
+				const dr = result.data as {
+					wouldExecute: boolean;
+					actions: Array<{ type: string; description: string }>;
+				};
+				return {
+					content: [
+						{
+							type: 'text',
+							text: [
+								'# WordPress Agent Kit — Dry Run',
+								'',
+								'## Changes',
+								...dr.actions.map((a) => `- **${a.type}**: ${a.description}`),
+								'',
+								'Run without `dryRun` to apply.',
+							].join('\n'),
+						},
+					],
+					details: dr,
+				};
+			}
+
+			// Real result
+			const data = result.data as {
+				filesCreated: string[];
+				filesSkipped: string[];
+				isUpdate: boolean;
+				backupDir: string | null;
+				conflicts?: string[];
+			};
+
+			const lines = [
+				data.isUpdate ? '# Updated' : '# Installed',
+				'',
+				`**Target**: ${opts.targetDir}`,
+				`**Files**: ${data.filesCreated.length} created/updated`,
+			];
+
+			if (data.filesSkipped.length > 0) {
+				lines.push(`**Preserved**: ${data.filesSkipped.length} files (user-modified)`);
+			}
+
+			if (data.conflicts?.length) {
+				lines.push('', '⚠ **Conflicts** (re-run with `force: true` to overwrite):');
+				for (const c of data.conflicts.slice(0, 5)) lines.push(`- ${c}`);
+			}
+
+			if (data.backupDir) lines.push('', `**Backup**: ${data.backupDir}`);
+
+			lines.push(
+				'',
+				'## Next Steps',
+				'1. Run `wp_triage` to detect project type',
+				'2. Review `AGENTS.md` for guidance'
+			);
+
+			return {
+				content: [{ type: 'text', text: lines.join('\n') }],
+				details: data,
+			};
+		},
+	});
+
+	// --- wp_sync_skills ---
+	pi.registerTool({
+		name: 'wp_sync_skills',
+		label: 'WP Sync Skills',
+		description:
+			'Sync WordPress agent skills from the upstream WordPress/agent-skills repository. Fetches the latest 17 skill definitions and replaces the local skills directory.',
+		promptSnippet: 'Sync latest WordPress agent skills from upstream',
+		promptGuidelines: [
+			'Use wp_sync_skills to pull the latest WordPress development skills from WordPress/agent-skills.',
+		],
+		parameters: Type.Object({
+			ref: Type.Optional(
+				Type.String({
+					description: 'Git ref to sync from (default: trunk)',
+				})
+			),
+		}),
+		async execute(_callId, params, _signal, onUpdate, _ctx) {
+			onUpdate?.({ content: [{ type: 'text', text: 'Syncing from WordPress/agent-skills...' }] });
+
+			const result = await syncSkillsApi({
+				targetDir: PACKAGE_ROOT,
+				ref: params.ref || 'trunk',
+			});
+
+			if (!result.success) {
+				return {
+					content: [
+						{ type: 'text', text: `Sync failed: ${result.error?.message || 'Unknown error'}` },
+					],
+					isError: true,
+				};
+			}
+
+			const data = result.data as { skillsSynced: number; method: string };
+			return {
+				content: [
+					{
+						type: 'text',
+						text: `# Skills Synced\n\n**Synced**: ${data.skillsSynced} skills\n**Method**: ${data.method}`,
+					},
+				],
+				details: data,
+			};
+		},
+	});
+
+	// --- wp_upgrade ---
+	pi.registerTool({
+		name: 'wp_upgrade',
+		label: 'WP Upgrade',
+		description:
+			'Check for WordPress Agent Kit updates. Shows current vs latest version and can preview or apply upgrades.',
+		promptSnippet: 'Check WordPress Agent Kit version',
+		promptGuidelines: [
+			'Use wp_upgrade to check if the installed WordPress Agent Kit is up to date.',
+			'Use wp_upgrade with checkOnly: true to preview without applying.',
+		],
+		parameters: Type.Object({
+			targetDir: Type.Optional(
+				Type.String({
+					description: 'Project directory to check (defaults to cwd)',
+				})
+			),
+			checkOnly: Type.Optional(
+				Type.Boolean({
+					description: 'Only check for updates, do not apply (default: false)',
+				})
+			),
+		}),
+		async execute(_callId, params, _signal, _onUpdate, _ctx) {
+			const targetDir = params.targetDir || process.cwd();
+			const checkOnly = params.checkOnly ?? false;
+			const manifest = loadManifest(targetDir, 'pi') || loadManifest(targetDir, 'github');
+			const currentVersion = manifest?.version || 'not installed';
+			const latestVersion = (() => {
+				try {
+					const fs = require('node:fs');
+					return JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf-8'))
+						.version;
+				} catch {
+					return 'unknown';
+				}
+			})();
+
+			const installed = isKitInstalled(targetDir, 'pi') || isKitInstalled(targetDir, 'github');
+
+			if (checkOnly) {
+				return {
+					content: [
+						{
+							type: 'text',
+							text: [
+								'# WordPress Agent Kit — Version Check',
+								'',
+								`**Installed**: ${installed ? 'yes' : 'no'}`,
+								`**Current**: ${currentVersion}`,
+								`**Latest**: ${latestVersion}`,
+								'',
+								currentVersion !== latestVersion && installed
+									? '⚠ Update available. Run without `checkOnly` to apply.'
+									: installed
+										? '✅ Up to date.'
+										: 'Not installed. Use `wp_install_kit` to install.',
+							].join('\n'),
+						},
+					],
+					details: { currentVersion, latestVersion, installed },
+				};
+			}
+
+			if (!installed) {
+				return {
+					content: [{ type: 'text', text: 'Kit not installed. Use `wp_install_kit` first.' }],
+					isError: true,
+				};
+			}
+
+			const result = await installKitApi({
+				targetDir,
+				platform: 'pi',
+				safe: true,
+				backup: true,
+			});
+
+			if (!result.success) {
+				return {
+					content: [{ type: 'text', text: `Upgrade failed: ${result.error?.message}` }],
+					isError: true,
+				};
+			}
+
+			const data = result.data as {
+				filesCreated: string[];
+				filesSkipped: string[];
+				conflicts?: string[];
+			};
+			const lines = [
+				'# Upgraded',
+				'',
+				`**Version**: ${currentVersion} → ${latestVersion}`,
+				`**Files updated**: ${data.filesCreated.length}`,
+			];
+			if (data.filesSkipped.length)
+				lines.push(`**Preserved**: ${data.filesSkipped.length} (user-modified)`);
+			if (data.conflicts?.length)
+				lines.push(`⚠ ${data.conflicts.length} conflicts (use force: true)`);
+
+			return {
+				content: [{ type: 'text', text: lines.join('\n') }],
+				details: data,
+			};
+		},
+	});
+
+	// =========================================================================
+	// Commands
+	// =========================================================================
+
+	pi.registerCommand('wp-triage', {
+		description: 'Run WordPress project triage detection',
+		handler: async (args, ctx) => {
+			const targetDir = args?.trim() || ctx.cwd;
+			ctx.ui.setStatus('wp-triage', 'Running triage...');
+			const result = await runTriageApi({ targetDir, platform: 'pi' });
+			if (!result.success) {
+				ctx.ui.notify(`Triage failed: ${result.error?.message}`, 'error');
+				return;
+			}
+			const t = result.data;
+			const summary = t.project
+				? `${t.project.primary} (confidence: ${t.project.confidence})`
+				: 'unknown';
+			ctx.ui.notify(`Project: ${summary}`, 'info');
+			ctx.ui.setStatus('wp-triage', summary);
+		},
+	});
+
+	pi.registerCommand('wp-install', {
+		description: 'Install WordPress Agent Kit into current project',
+		handler: async (args, ctx) => {
+			const targetDir = args?.trim() || ctx.cwd;
+			ctx.ui.setStatus('wp-install', 'Installing...');
+			const result = await installKitApi({ targetDir, platform: 'pi', safe: true, backup: true });
+			if (!result.success) {
+				ctx.ui.notify(`Install failed: ${result.error?.message}`, 'error');
+				return;
+			}
+			const data = result.data as { filesCreated: string[]; isUpdate: boolean };
+			ctx.ui.notify(
+				`${data.isUpdate ? 'Updated' : 'Installed'} (${data.filesCreated.length} entries)`,
+				'info'
+			);
+			ctx.ui.setStatus('wp-agent-kit', 'v0.3.0 installed');
+		},
+	});
+
+	pi.registerCommand('wp-sync-skills', {
+		description: 'Sync WordPress skills from upstream',
+		handler: async (args, ctx) => {
+			ctx.ui.setStatus('wp-sync', 'Syncing...');
+			const result = await syncSkillsApi({ targetDir: PACKAGE_ROOT, ref: args?.trim() || 'trunk' });
+			if (!result.success) {
+				ctx.ui.notify(`Sync failed: ${result.error?.message}`, 'error');
+				return;
+			}
+			const data = result.data as { skillsSynced: number };
+			ctx.ui.notify(`Synced ${data.skillsSynced} skills`, 'info');
+			ctx.ui.setStatus('wp-agent-kit', `${data.skillsSynced} skills`);
+		},
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wordpress-agent-kit",
-  "version": "0.2.2",
+  "version": "0.3.2",
   "description": "WordPress-focused AGENTS.md + Agent Skills starter kit for AI coding agents.",
   "license": "GPL-2.0-or-later",
   "author": "Kyle Brodeur <kyle@brodeur.me> (https://brodeur.me)",
@@ -13,7 +13,8 @@
     "agents-md",
     "agent-skills",
     "ai-coding",
-    "copilot"
+    "copilot",
+    "pi-package"
   ],
   "engines": {
     "node": ">=20.18"
@@ -21,10 +22,26 @@
   "bin": {
     "wp-agent-kit": "dist/cli.js"
   },
+  "exports": {
+    ".": "./dist/cli.js",
+    "./api": "./dist/lib/api.js"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/wp-agent-kit"
+    ],
+    "skills": [
+      "./.github/skills"
+    ]
+  },
   "dependencies": {
     "@clack/prompts": "^0.8.2",
     "commander": "^13.0.0"
   },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
     "@eslint/js": "^9.17.0",
@@ -38,7 +55,8 @@
     "typescript": "^5.7.2",
     "typescript-eslint": "^8.18.0",
     "vitest": "^2.1.8",
-    "@earendil-works/pi-coding-agent": "^0.78.1"
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "typebox": "*"
   },
   "scripts": {
     "dev": "tsx src/cli.ts",

package/kit-learnings.md

@@ -1,192 +0,0 @@
-# WordPress Agent Kit - Installation & Usage Learnings
-
-**Package:** `wordpress-agent-kit@0.2.1` (published on npm)
-**Author:** Kyle Brodeur
-**Repo:** https://github.com/kylebrodeur/wordpress-agent-kit
-
----
-
-## Quick Start (What Actually Works)
-
-### For Pi (Recommended)
-```bash
-pnpm dlx wordpress-agent-kit@latest install --platform pi
-```
-- Installs skills to `.pi/agent/skills/` (17 skills)
-- Non-interactive, no TTY needed
-- Works in headless/CI environments
-
-### For Other Platforms
-```bash
-# GitHub Copilot / VS Code
-pnpm dlx wordpress-agent-kit@latest install --platform github
-
-# Cursor IDE
-pnpm dlx wordpress-agent-kit@latest install --platform cursor
-
-# Generic agent format
-pnpm dlx wordpress-agent-kit@latest install --platform agent
-
-# Claude (interactive - requires TTY)
-pnpm dlx wordpress-agent-kit@latest install --platform claude
-```
-
----
-
-## What DOESN'T Work (Common Pitfalls)
-
-### `setup` command requires TTY
-```bash
-pnpm dlx wordpress-agent-kit@latest setup  # FAILS in non-interactive shells
-```
-**Error:** `ERR_TTY_INIT_FAILED: uv_tty_init returned EINVAL (invalid argument)`
-
-The `setup` command uses `@clack/prompts` for interactive prompts, which requires a real TTY. It fails in:
-- CI/CD pipelines
-- Docker containers without `-it`
-- Non-interactive SSH sessions
-- Most AI agent execution environments
-
-**Workaround:** Use `install --platform <platform>` instead.
-
----
-
-## Platform Comparison
-
-| Platform | Target Dir | Interactive? | Best For |
-|----------|------------|--------------|----------|
-| `pi` | `.pi/agent/skills/` | ❌ No | **Pi Coding Agent** (this project) |
-| `github` | `.github/skills/` | ❌ No | GitHub Copilot, VS Code |
-| `cursor` | `.cursor/skills/` | ❌ No | Cursor IDE |
-| `agent` | `.agent/skills/` | ❌ No | Generic `.agent` workflows |
-| `claude` | `.claude/skills/` | ✅ Yes | Claude Code (interactive only) |
-
----
-
-## Skills Installed (17 Total)
-
-All synced from `WordPress/agent-skills` trunk:
-
-1. `wp-abilities-api` - Abilities API registration & consumption
-2. `wp-abilities-audit` - Audit plugin REST surface for Abilities
-3. `wp-abilities-verify` - Verify Abilities registrations
-4. `wp-block-development` - Gutenberg blocks: block.json, attributes, rendering
-5. `wp-block-themes` - Block themes: theme.json, templates, patterns
-6. `wp-interactivity-api` - data-wp-* directives & stores
-7. `wp-performance` - Profiling, caching, DB optimization
-8. `wp-phpstan` - PHPStan config for WordPress
-9. `wp-playground` - WordPress Playground for instant environments
-10. `wp-plugin-development` - Plugin architecture, hooks, Settings API, security
-11. `wp-plugin-directory-guidelines` - WP Plugin Directory requirements
-12. `wp-project-triage` - Auto-detect project type, tooling, versions
-13. `wp-rest-api` - REST API routes, schema, auth, response shaping
-14. `wp-wpcli-and-ops` - WP-CLI commands, automation, multisite
-15. `wpds` - WordPress Design System
-16. `blueprint` - Playground Blueprints for declarative setup
-17. `wordpress-router` - Classifies WP repos, routes to right workflow
-
----
-
-## Verification Commands
-
-After installation, verify everything works:
-
-```bash
-# 1. Check skills installed
-ls -la .pi/agent/skills/
-
-# 2. Run project triage (detects WP project type)
-node .pi/agent/skills/wp-project-triage/scripts/detect_wp_project.mjs
-
-# 3. Run design-system tests (if applicable)
-cd design-system && pnpm test && pnpm run typecheck
-
-# 4. PHP syntax check
-find wpaos wpaos-blocks -name '*.php' -exec php -l {} \;
-```
-
----
-
-## Key Files & Locations
-
-```
-wordpress-agent-kit/
-├── package.json                 # Package definition (name: wordpress-agent-kit)
-├── src/
-│   ├── cli.ts                   # Main CLI entry
-│   ├── commands/
-│   │   ├── install.ts           # Non-interactive install (USE THIS)
-│   │   ├── setup.ts             # Interactive setup (NEEDS TTY)
-│   │   ├── sync-skills.ts       # Pulls from WordPress/agent-skills
-│   │   └── playground.ts        # Local WP Playground
-│   └── utils/
-│       └── platforms.ts         # Platform definitions (pi, github, cursor, agent, claude)
-├── dist/bundles/                # Pre-built tarballs (legacy method)
-└── vendor/wp-agent-skills/      # Synced upstream skills (gitignored)
-```
-
----
-
-## Syncing Latest Upstream Skills
-
-The kit bundles skills at release time. To get latest:
-
-```bash
-# From kit repo (if contributing)
-pnpm sync:skills
-pnpm build:bundles
-
-# Or just reinstall (pulls latest from npm)
-pnpm dlx wordpress-agent-kit@latest install --platform pi --force
-```
-
----
-
-## Integration with This Project (wp-agent-os)
-
-### AGENTS.md References
-The project's `AGENTS.md` still references `.github/skills/` but we use `.pi/agent/skills/`. The skills are the same - just different install locations.
-
-### wp-abilities-api Verification
-Verified that `wpaos/includes/abilities.php` uses correct arg keys per the skill:
-- `label`, `description`, `category`, `input_schema`, `output_schema`
-- `permission_callback`, `execute_callback`, `meta`
-- `meta.show_in_rest: true`, `meta.mcp.public: true`
-
-### CI/CD Usage
-```yaml
-# GitHub Actions example
-- name: Install WordPress Agent Kit
-  run: pnpm dlx wordpress-agent-kit@latest install --platform github
-```
-
----
-
-## Troubleshooting
-
-### "Command not found" / 404 on npm
-- Package name is `wordpress-agent-kit` (NOT `wp-agent-kit`)
-- Published to npm as `kylebrodeur` scope would be `@kylebrodeur/wordpress-agent-kit` but it's unscoped
-
-### Skills not showing up
-- Check install location matches your agent's config (`.pi/agent/skills/` for Pi)
-- Run with `--force` to overwrite existing
-
-### Old placeholder skills remain
-- Delete old skill directories before reinstall:
-  ```bash
-  rm -rf .claude/skills .github/skills .cursor/skills .agent/skills
-  pnpm dlx wordpress-agent-kit@latest install --platform pi
-  ```
-
----
-
-## Summary: Recommended Workflow for This Project
-
-```bash
-# One-liner for clean install in any environment
-rm -rf .claude/skills .github/skills .cursor/skills .agent/skills .pi/agent/skills && \
-pnpm dlx wordpress-agent-kit@latest install --platform pi
-```
-
-Then the skills live in `.pi/agent/skills/` and are available to Pi automatically.