wordpress-agent-kit 0.2.1 → 0.3.0

package/README.md

@@ -2,117 +2,289 @@
 
 [![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg?style=flat-square)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/Written%20in-TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
-[![Version](https://img.shields.io/badge/version-0.2.0-blue?style=flat-square)](package.json)
+[![Version](https://img.shields.io/badge/version-0.3.0-blue?style=flat-square)](package.json)
+[![Node](https://img.shields.io/badge/node-%3E%3D20.18-green?style=flat-square)](package.json)
+[![CI](https://img.shields.io/badge/CI-passing-brightgreen?style=flat-square)](.github/workflows/ci.yml)
 
-**WordPress-focused AI agent starter kit** for GitHub Copilot, Claude, and other LLM coding agents. Includes instructions, specialized WordPress skills, and workflow automation aligned with industry standards.
+**WordPress-focused AI agent starter kit** for GitHub Copilot, Cursor, Claude, and Pi Coding Agent. Installs 13 specialized WordPress agent skills, an agent persona, workflow instructions, and AGENTS.md configuration — everything an AI coding agent needs to build WordPress plugins, themes, and blocks correctly.
 
 Maintained by [Kyle Brodeur](https://brodeur.me).
 
-## Quick Start
+---
 
-### Option 1: CLI (Recommended)
+## Getting Started
 
-Run the interactive setup wizard:
+Choose your scenario:
+
+### Scenario 1: Brand New WordPress Project
 
 ```bash
-npx wp-agent-kit setup
-# or
-pnpm dlx wp-agent-kit setup
+# 1. Install the kit (copies skills, agents, instructions, AGENTS.md template)
+npx wp-agent-kit install /path/to/my-plugin --platform github
+
+# 2. Run auto-setup (detects project type and configures AGENTS.md)
+npx wp-agent-kit setup /path/to/my-plugin --auto
+
+# 3. (Optional) Verify the triage report
+node .github/skills/wp-project-triage/scripts/detect_wp_project.mjs
 ```
 
-This will:
-- Detect your WordPress project type
-- Install `AGENTS.md` and skills into your project
-- Configure for your tech stack
+**What gets installed:**
+```
+my-plugin/
+├── AGENTS.md                  # Project-specific agent instructions
+├── AGENTS.template.md         # Template reference for future updates
+├── .github/
+│   ├── agents/
+│   │   └── wp-architect.agent.md    # WordPress Architect agent persona
+│   ├── instructions/
+│   │   └── wordpress-workflow.instructions.md
+│   ├── prompts/
+│   └── skills/                      # 13 WordPress skills
+│       ├── wp-project-triage/       # Project detection
+│       ├── wp-plugin-development/   # Plugin architecture
+│       ├── wp-block-development/    # Gutenberg blocks
+│       ├── wp-block-themes/         # Block themes
+│       ├── wp-rest-api/             # REST API
+│       ├── wp-interactivity-api/    # Interactivity API
+│       ├── wp-abilities-api/        # Abilities API
+│       ├── wp-performance/          # Performance profiling
+│       ├── wp-phpstan/              # Static analysis
+│       ├── wp-wpcli-and-ops/        # WP-CLI operations
+│       ├── wp-playground/           # Testing environments
+│       ├── wpds/                    # Design system
+│       └── wordpress-router/        # Repo classification
+└── .wp-agent-kit-manifest.github.json  # Safe-update tracking
+```
 
-### Option 2: Pre-built Bundles
+### Scenario 2: Existing WordPress Project
 
-Download a bundle from the [latest release](https://github.com/kylebrodeur/wordpress-agent-kit/releases):
+```bash
+# 1. Install kit (preserves your existing AGENTS.md)
+npx wp-agent-kit install /path/to/existing-plugin --platform github
 
-- **`wordpress-agent-kit-github.tar.gz`** - For GitHub Copilot
-- **`wordpress-agent-kit-claude.tar.gz`** - For Claude
-- **`wordpress-agent-kit-agent.tar.gz`** - For generic `.agent` workflows
-- **`wordpress-agent-kit-cursor.tar.gz`** - For Cursor IDE
+# 2. Run triage to detect your project's type, tech stack, and tooling
+node .github/skills/wp-project-triage/scripts/detect_wp_project.mjs
 
-Extract into your WordPress project root:
+# 3. Configure based on detection (headless)
+npx wp-agent-kit setup /path/to/existing-plugin --auto
 
-```bash
-cd /path/to/your-wordpress-project
-tar -xzf wordpress-agent-kit-github.tar.gz
+# Or specify explicitly
+npx wp-agent-kit setup /path/to/existing-plugin \
+  --project-type plugin \
+  --tech-stack gutenberg,rest-api,wpcli,composer,npm \
+  --package-manager pnpm \
+  --yes
 ```
 
-This interactive setup helps you:
-- **Automatically detect** your project type and technologies.
-- Customize `AGENTS.md` for your tech stack.
-- Configure workflow instructions.
-- Set up prompt templates.
+**Key behavior:**
+- Your existing `AGENTS.md` is **never overwritten** — only new sections are added
+- Triage inspects your codebase and returns structured JSON with project kind, signals, and tooling
+- Setup updates only the tooling/configuration sections of AGENTS.md
 
-Use the `--reset` flag if you need to re-run the setup on an existing project:
+### Scenario 3: Upgrading an Existing Kit Installation
 
 ```bash
-pnpm setup -- /path/to/your-wp-project --reset
+# Check if an update is available
+npx wp-agent-kit upgrade --check-only
+
+# Preview what would change (dry-run)
+npx wp-agent-kit install --dry-run
+
+# Apply safe update (preserves your modifications)
+npx wp-agent-kit upgrade --force
 ```
 
-The setup will analyze your project first and either:
-- Auto-configure if confident.
-- Pre-fill smart defaults if partially detected.
-- Ask questions if detection is unclear.
+**Safe update behavior:**
+- Compares installed files against a manifest of original hashes
+- Files you haven't modified → automatically updated
+- Files you modified → **skipped** (preserved)
+- Use `--force` to overwrite your modifications with upstream changes
+- A backup is created at `.wp-agent-kit-backup-{timestamp}/` before making changes
 
-## Who This Is For
+```bash
+# Emergency: override all safety and replace everything
+npx wp-agent-kit install --no-safe --force
+```
 
-- **WordPress plugin/theme developers** who want AI agents to understand WordPress conventions (hooks, sanitization, Settings API, block registration, etc.).
-- **Teams adopting GitHub Copilot or Claude** for WordPress codebases.
-- **Anyone building custom WordPress workflows** who needs agents to follow WordPress Coding Standards, security best practices, and core APIs.
+---
 
-## What You Get
+## Quick Reference
 
-- **Agent Skills**: WordPress-specific knowledge modules (blocks, Interactivity API, REST API, WP-CLI, performance, security, theme.json, Playground, PHPStan, etc.).
-- **Instructions & Workflows**: Pre-built guidance for common WordPress dev cycles.
-- **AGENTS.md**: Single-file agent onboarding that loads skills on demand.
-- **Sync Scripts**: Pull latest skills from official [WordPress/agent-skills](https://github.com/WordPress/agent-skills) repository.
+### CLI Commands
 
-## Development
+| Command | Purpose |
+|---------|---------|
+| `install [dir]` | Install kit into a project |
+| `setup [dir]` | Interactive or headless configuration |
+| `sync-skills [ref]` | Pull latest skills from WordPress/agent-skills |
+| `upgrade [dir]` | Check or apply version upgrades |
+| `playground` | Launch local WordPress Playground |
 
-This project uses a TypeScript-based CLI for all operations.
+### Platform Flags
 
-### Build CLI
+| Platform | Flag | Target Directory |
+|----------|------|-----------------|
+| GitHub Copilot / VS Code | `--platform github` | `.github/` |
+| Cursor IDE | `--platform cursor` | `.cursor/` |
+| Claude Code | `--platform claude` | `.claude/` |
+| Pi Coding Agent | `--platform pi` | `.pi/agent/` |
+| Generic .agent | `--platform agent` | `.agent/` |
 
-```bash
-pnpm build
-```
+### Agent-Friendly Flags (All Commands)
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Machine-readable JSON output |
+| `--dry-run` | Preview changes without applying |
+| `--ndjson` | Newline-delimited JSON for streaming |
+| `--quiet` | Suppress non-error output |
+
+---
+
+## Pi Coding Agent Integration
 
-### Build Release Bundles
+This package is also a Pi extension — install it once and all WordPress skills and tools are available to Pi:
 
 ```bash
-pnpm sync:skills  # Sync latest WordPress skills first
-pnpm build:bundles
+pi install npm:wordpress-agent-kit
 ```
 
-This generates four platform-specific bundles in `dist/bundles/`:
-- `wordpress-agent-kit-github.tar.gz`
-- `wordpress-agent-kit-claude.tar.gz`
-- `wordpress-agent-kit-agent.tar.gz`
-- `wordpress-agent-kit-cursor.tar.gz`
+### Pi Tools (Callable by the Agent)
+
+| Tool | What it does |
+|------|-------------|
+| `wp_triage` | Detect WordPress project type, signals, and tooling |
+| `wp_install_kit` | Install/update kit into a project (safe by default) |
+| `wp_sync_skills` | Sync skills from WordPress/agent-skills upstream |
+| `wp_upgrade` | Check and apply version upgrades |
+
+### Pi Commands (Type `/` in Pi TUI)
+
+| Command | What it does |
+|---------|-------------|
+| `/wp-triage [dir]` | Run project detection, show in status bar |
+| `/wp-install [dir]` | Install kit into current project |
+| `/wp-sync-skills [ref]` | Sync skills from upstream |
+| `/wp-upgrade` | Show installed vs latest version |
+
+---
+
+## Programmatic API
+
+Import directly into scripts, tests, or other tools:
+
+```typescript
+import {
+  installKitApi,         // Install/update kit
+  syncSkillsApi,         // Sync skills from upstream
+  runTriageApi,          // Run project detection
+  configureAgentsMdApi,  // Configure AGENTS.md
+  computeChanges,        // Preview file changes (dry-run)
+  isKitInstalled,        // Check if kit is installed
+  loadManifest,          // Read install manifest
+  updateKit,             // Raw safe update
+  ExitCode,              // Semantic exit codes
+} from 'wordpress-agent-kit/api';
+
+// Install with safe update
+const result = await installKitApi({
+  targetDir: '/path/to/my-plugin',
+  platform: 'github',
+  safe: true,     // Use manifest-based diff
+  backup: true,   // Create backup before changes
+  force: false,   // Don't overwrite user mods
+});
+
+// Dry-run preview
+const preview = await installKitApi({
+  targetDir: '/path/to/my-plugin',
+  platform: 'github',
+  dryRun: true,
+});
+// preview.data.actions → [{ type: 'create', target: '...', description: '...' }]
+
+// Detect project type
+const triage = await runTriageApi({ targetDir: '/path/to/project' });
+console.log(triage.data.project.primary); // "plugin"
+```
+
+### Semantic Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 2 | Invalid arguments |
+| 3 | Not found |
+| 4 | Permission denied |
+| 5 | Already exists |
+| 6 | Git error |
+| 7 | Network error |
+| 8 | Validation failed |
+| 130 | Cancelled |
+
+---
+
+## Skills Reference
+
+All 13 skills follow the [AgentSkills.io](https://agentskills.io) specification:
+
+| Skill | When to Use |
+|-------|------------|
+| `wordpress-router` | Classify a WordPress repo and route to the right workflow |
+| `wp-project-triage` | Run deterministic project detection (type, tooling, versions) |
+| `wp-plugin-development` | Develop WordPress plugins (hooks, settings, security, release) |
+| `wp-block-development` | Develop Gutenberg blocks (block.json, attributes, rendering) |
+| `wp-block-themes` | Develop block themes (theme.json, templates, patterns, variations) |
+| `wp-rest-api` | Build, extend, or debug REST API endpoints/routes |
+| `wp-interactivity-api` | Build Interactive blocks with data-wp-* directives |
+| `wp-abilities-api` | Register and consume WordPress Abilities API |
+| `wp-performance` | Profile and optimize WordPress performance |
+| `wp-phpstan` | Configure and run PHPStan static analysis |
+| `wp-wpcli-and-ops` | WP-CLI commands, automation, multisite operations |
+| `wp-playground` | Test in disposable WordPress Playground instances |
+| `wpds` | Build UIs with the WordPress Design System |
+
+---
 
-### Run Tests
+## Development
 
 ```bash
-pnpm test
+# Install dependencies
+pnpm install
+
+# Run in dev mode
+pnpm dev
+
+# Type-check
+pnpm check
+
+# Lint & format
+pnpm lint:check
+pnpm format
+
+# Run tests
+pnpm test:run
+
+# Build for distribution
+pnpm build
+
+# Full pre-publish check (build + lint + test)
+pnpm prepublishOnly
 ```
 
-## Customization
+---
 
-**Quick method:** Run the interactive setup.
+## Documentation
 
-**Manual method:** Edit files directly:
+- **[CLI_REVIEW.md](CLI_REVIEW.md)** — Initial architecture review and design decisions
+- **[CHANGELOG.md](CHANGELOG.md)** — Version history and release notes
+- **[AGENTS.md](AGENTS.md)** — Agent instructions for this repository
 
-1. Edit `AGENTS.md` to match your project's tech stack and conventions.
-2. Run WordPress project triage (via `wp-project-triage` skill) to generate tailored instructions.
-3. Update `.github/instructions/wordpress-workflow.instructions.md` with your workflow.
-4. Keep prompts in `.github/prompts/` accurate for your plugin/theme.
+---
 
 ## Credits
 
-- **[AGENTS.md](https://agentskills.io)** - The agent configuration standard.
-- **[AgentSkills.io](https://agentskills.io)** - The open directory of agent skills.
+- **[AgentSkills.io](https://agentskills.io)** — The agent skills specification
+- **[AGENTS.md](https://agentskills.io)** — The agent configuration standard
+- **[WordPress/agent-skills](https://github.com/WordPress/agent-skills)** — Upstream skills repository

package/biome.json

@@ -0,0 +1,39 @@
+{
+	"$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"
+		}
+	}
+}

package/dist/cli.js

@@ -1,19 +1,90 @@
 #!/usr/bin/env node
+import { createRequire } from 'node:module';
 import { Command } from 'commander';
-import { createRequire } from 'module';
 import { installCommand } from './commands/install.js';
+import { runPlaygroundCommand } from './commands/run-playground.js';
 import { setupCommand } from './commands/setup.js';
 import { syncSkillsCommand } from './commands/sync-skills.js';
-import { runPlaygroundCommand } from './commands/run-playground.js';
+import { upgradeCommand } from './commands/upgrade.js';
+import { ExitCode } from './utils/exit-codes.js';
+import { createFormatter } from './utils/output.js';
+import { OutputFormatter } from './utils/output.js';
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
 const program = new Command();
+// Global options for all commands
 program
     .name('wp-agent-kit')
     .description('Utilities for WordPress Agent Kit')
-    .version(version);
+    .version(version)
+    .option('--json', 'Output JSON result to stdout', false)
+    .option('--quiet', 'Suppress all output except errors', false)
+    .option('--ndjson', 'Output NDJSON progress events (for long operations)', false)
+    .option('--dry-run', 'Preview actions without executing', false)
+    .configureHelp({
+    sortSubcommands: true,
+});
+// Add commands
 program.addCommand(installCommand);
 program.addCommand(setupCommand);
 program.addCommand(syncSkillsCommand);
 program.addCommand(runPlaygroundCommand);
-program.parse(process.argv);
+program.addCommand(upgradeCommand);
+// Global error handler
+program.exitOverride((err) => {
+    if (err.code === 'commander.helpDisplayed' || err.code === 'commander.versionDisplayed') {
+        process.exit(ExitCode.OK);
+    }
+    if (err.code === 'commander.unknownOption' || err.code === 'commander.invalidArgument') {
+        const formatter = createFormatter({ json: true }, 'wp-agent-kit', version);
+        const result = formatter.fail({
+            code: 'INVALID_ARGS',
+            message: err.message,
+            exitCode: ExitCode.INVALID_ARGS,
+        });
+        process.exit(OutputFormatter.getExitCode(result));
+    }
+    throw err;
+});
+// Custom help with examples
+program.addHelpText('after', `
+Examples:
+  $ wp-agent-kit install --platform github
+  $ wp-agent-kit setup --auto --json
+  $ wp-agent-kit sync-skills --ref trunk --ndjson
+  $ wp-agent-kit install --platform pi --dry-run --json
+  $ wp-agent-kit upgrade --check-only --json
+
+Programmatic API:
+  import { installKit, syncSkills, runTriage } from 'wordpress-agent-kit/api';
+
+For more info: https://github.com/kylebrodeur/wordpress-agent-kit
+`);
+try {
+    program.parse(process.argv);
+}
+catch (error) {
+    // Handle errors from commands that use process.exit
+    const err = error;
+    if (err.exitCode !== undefined) {
+        process.exit(err.exitCode);
+    }
+    // Fallback for unexpected errors
+    const formatter = createFormatter({ json: true }, 'wp-agent-kit', version);
+    const result = formatter.fail({
+        code: 'UNEXPECTED_ERROR',
+        message: error instanceof Error ? error.message : 'Unknown error',
+        exitCode: ExitCode.ERROR,
+    });
+    process.exit(OutputFormatter.getExitCode(result));
+}
+// Handle unhandled rejections
+process.on('unhandledRejection', (reason) => {
+    const formatter = createFormatter({ json: true }, 'wp-agent-kit', version);
+    const result = formatter.fail({
+        code: 'UNHANDLED_REJECTION',
+        message: reason instanceof Error ? reason.message : String(reason),
+        exitCode: ExitCode.ERROR,
+    });
+    process.exit(OutputFormatter.getExitCode(result));
+});

package/dist/commands/install.js

@@ -1,27 +1,101 @@
-import { Command } from 'commander';
 import path from 'node:path';
-import { installKit } from '../lib/installer.js';
+import { Command } from 'commander';
+import { installKitApi, isKitInstalled, loadManifest, } from '../lib/api.js';
+import { OutputFormatter, createFormatter } from '../utils/output.js';
+function isDryRunResult(result) {
+    return result.success && 'wouldExecute' in (result.data || {});
+}
+function isRegularResult(result) {
+    return result.success && !('wouldExecute' in (result.data || {}));
+}
 /**
  * Command to install the WordPress Agent Kit into a target directory.
  * Takes an optional directory argument, defaulting to the current working directory.
+ * Supports --json, --quiet, --ndjson, --dry-run global flags.
+ * Safe update mode preserves user modifications on re-install.
  */
 export const installCommand = new Command('install')
     .description('Install the WordPress Agent Kit into a target directory')
     .argument('[dir]', 'Target directory to install into', process.cwd())
     .option('--platform <platform>', 'Target platform (github, cursor, claude, agent, pi)', 'github')
-    .action(async (dir, options) => {
+    .option('--force', 'Overwrite user modifications on update', false)
+    .option('--no-safe', 'Disable safe update (use full nuke-and-replace)')
+    .option('--no-backup', 'Skip creating a backup before overwriting files')
+    .action(async (dir, options, command) => {
+    const globalOpts = command.parent?.opts() || {};
     const platform = options.platform;
     const validPlatforms = ['github', 'cursor', 'claude', 'agent', 'pi'];
     if (!validPlatforms.includes(platform)) {
-        console.error(`Invalid platform: ${platform}. Valid options: ${validPlatforms.join(', ')}`);
-        process.exit(1);
+        const formatter = createFormatter(globalOpts, 'install', '0.0.0');
+        const result = formatter.fail({
+            code: 'INVALID_PLATFORM',
+            message: `Invalid platform: ${platform}. Valid options: ${validPlatforms.join(', ')}`,
+            exitCode: 2,
+        });
+        process.exit(OutputFormatter.getExitCode(result));
     }
     const targetDir = path.resolve(dir);
-    try {
-        await installKit(targetDir, platform);
+    const isUpdate = isKitInstalled(targetDir, platform);
+    const existingManifest = loadManifest(targetDir, platform);
+    const installOptions = {
+        targetDir,
+        platform: platform,
+        force: options.force,
+        dryRun: globalOpts.dryRun,
+        safe: options.safe !== false, // Default: true (safe)
+        backup: options.backup !== false, // Default: true
+    };
+    const result = await installKitApi(installOptions);
+    if (globalOpts.json || globalOpts.ndjson || globalOpts.quiet) {
+        process.exit(OutputFormatter.getExitCode(result));
+    }
+    // Human-readable output
+    if (isRegularResult(result)) {
+        const data = result.data;
+        if (isUpdate) {
+            console.log(`✓ Updated WordPress Agent Kit (${platform}) in ${targetDir}`);
+            if (existingManifest) {
+                console.log(`  Previous version: ${existingManifest.version}`);
+            }
+            console.log(`  Files: ${data.filesCreated.length} created/updated`);
+            if (data.filesSkipped.length > 0) {
+                console.log(`  Skipped: ${data.filesSkipped.length} files (user-modified, preserved)`);
+            }
+            if (data.conflicts && data.conflicts.length > 0) {
+                console.log(`\n⚠  ${data.conflicts.length} conflict(s) detected:`);
+                for (const conflict of data.conflicts) {
+                    console.log(`   - ${conflict}`);
+                }
+                console.log('   Re-run with --force to overwrite.');
+            }
+            if (data.backupDir) {
+                console.log(`  Backup: ${data.backupDir}`);
+            }
+        }
+        else {
+            console.log(`✓ Installed WordPress Agent Kit (${platform}) to ${targetDir}`);
+            console.log(`  Files: ${data.filesCreated.length} created, ${data.filesSkipped.length} skipped`);
+        }
+        console.log(`  Duration: ${data.durationMs}ms`);
+    }
+    else if (isDryRunResult(result)) {
+        const summary = result.data.summary;
+        if (isUpdate) {
+            console.log(`✓ Dry-run update (${platform}) for ${targetDir}:`);
+        }
+        else {
+            console.log(`✓ Dry-run install (${platform}) to ${targetDir}:`);
+        }
+        console.log(`  Would create: ${summary.filesCreated.length} files`);
+        if (summary.filesSkipped && summary.filesSkipped.length > 0) {
+            console.log(`  Would skip: ${summary.filesSkipped.length} files (user-modified)`);
+        }
+        if (summary.conflicts && summary.conflicts.length > 0) {
+            console.log(`  Conflicts: ${summary.conflicts.length} files (use --force to overwrite)`);
+        }
     }
-    catch (error) {
-        console.error(error.message);
-        process.exit(1);
+    else {
+        console.error(`✗ Installation failed: ${result.error?.message}`);
     }
+    process.exit(result.success ? 0 : 1);
 });