wordpress-agent-kit 0.2.1

package/dist/commands/setup.js

@@ -0,0 +1,237 @@
+import { Command } from 'commander';
+import * as p from '@clack/prompts';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { PACKAGE_ROOT } from '../utils/paths.js';
+import { installKit, PLATFORM_FOLDERS } from '../lib/installer.js';
+import { mapProjectType, mapTechStack, hasConfidentDetection, formatDetectionResults } from '../lib/triage-mapper.js';
+/**
+ * Command to interactively set up the WordPress Agent Kit.
+ * Handles detection of project type, installation, and configuration of AGENTS.md.
+ */
+export const setupCommand = new Command('setup')
+    .description('Interactive setup for WordPress Agent Kit')
+    .argument('[dir]', 'Target directory', process.cwd())
+    .option('--reset', 'Reset and overwrite existing configuration')
+    .option('--platform <platform>', 'Target platform (github, cursor, claude, agent, pi)', 'github')
+    .action(async (dir, options) => {
+    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 platformFolder = PLATFORM_FOLDERS[platform];
+    console.clear();
+    p.intro('WordPress Agent Kit Setup');
+    const targetDir = path.resolve(dir);
+    // Check if target directory exists
+    if (!fs.existsSync(targetDir)) {
+        const shouldCreate = await p.confirm({
+            message: `Target directory doesn't exist: ${targetDir}\nCreate it?`,
+            initialValue: true,
+        });
+        if (p.isCancel(shouldCreate) || !shouldCreate) {
+            p.cancel('Setup cancelled.');
+            process.exit(0);
+        }
+        try {
+            fs.mkdirSync(targetDir, { recursive: true });
+            p.log.success(`Created directory: ${targetDir}`);
+        }
+        catch (err) {
+            p.log.error(`Failed to create directory: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    p.log.info(`Setting up kit in: ${targetDir} (platform: ${platform})`);
+    // Check if kit is already installed
+    const agentsPath = path.join(targetDir, 'AGENTS.md');
+    const platformInstructionsPath = path.join(targetDir, platformFolder, 'instructions', 'wordpress-workflow.instructions.md');
+    if (options.reset && fs.existsSync(agentsPath)) {
+        const confirmReset = await p.confirm({
+            message: `Warning: --reset will overwrite existing AGENTS.md and ${platformFolder} configuration. Continue?`,
+            initialValue: false,
+        });
+        if (p.isCancel(confirmReset) || !confirmReset) {
+            p.cancel('Reset cancelled.');
+            process.exit(0);
+        }
+        // Force install if reset is confirmed
+        const s = p.spinner();
+        s.start('Re-installing kit files...');
+        try {
+            await installKit(targetDir, platform);
+            s.stop('Kit files reset.');
+        }
+        catch (err) {
+            s.stop('Reset failed.');
+            console.error(err.message);
+            process.exit(1);
+        }
+    }
+    else if (!fs.existsSync(agentsPath)) {
+        const shouldInstall = await p.confirm({
+            message: 'Kit not found in target repo. Install it first?',
+            initialValue: true,
+        });
+        if (p.isCancel(shouldInstall) || !shouldInstall) {
+            p.cancel('Setup cancelled.');
+            process.exit(0);
+        }
+        const s = p.spinner();
+        s.start('Installing kit files...');
+        try {
+            await installKit(targetDir, platform);
+            s.stop('Kit installed successfully.');
+        }
+        catch (err) {
+            s.stop('Installation failed.');
+            console.error(err.message);
+            process.exit(1);
+        }
+    }
+    // Run project triage BEFORE asking any questions
+    let triageResult = null;
+    let detectedType = null;
+    let detectedTech = [];
+    // Try to find triage script in multiple locations
+    const triageScriptPaths = [
+        path.join(targetDir, platformFolder, 'skills/wp-project-triage/scripts/detect_wp_project.mjs'),
+        path.join(process.cwd(), platformFolder, 'skills/wp-project-triage/scripts/detect_wp_project.mjs'),
+        path.resolve(PACKAGE_ROOT, 'vendor/wp-agent-skills/skills/wp-project-triage/scripts/detect_wp_project.mjs'),
+    ];
+    const triageScriptPath = triageScriptPaths.find(p => fs.existsSync(p));
+    if (triageScriptPath) {
+        const s = p.spinner();
+        s.start('Analyzing project structure...');
+        try {
+            const result = spawnSync('node', [triageScriptPath], {
+                cwd: targetDir,
+                encoding: 'utf-8',
+            });
+            if (result.status === 0 && result.stdout) {
+                triageResult = JSON.parse(result.stdout.trim());
+                detectedType = mapProjectType(triageResult.project?.primary);
+                detectedTech = mapTechStack(triageResult);
+            }
+            s.stop('Project analyzed.');
+        }
+        catch (err) {
+            s.stop('Auto-detection unavailable.');
+            p.log.warn('Could not run project triage. Proceeding with manual setup.');
+        }
+    }
+    else {
+        p.log.info('Project triage not available yet. Using manual setup.');
+    }
+    let detectedPackageManager = 'npm/pnpm';
+    if (triageResult && triageResult.tooling?.node?.packageManager) {
+        detectedPackageManager = triageResult.tooling.node.packageManager;
+    }
+    let useDetectedValues = false;
+    if (triageResult && hasConfidentDetection(detectedType, detectedTech)) {
+        p.note(formatDetectionResults(detectedType, detectedTech, triageResult), 'Auto-Detection Results');
+        const confirmDetection = await p.confirm({
+            message: 'Use these detected values?',
+            initialValue: true,
+        });
+        if (p.isCancel(confirmDetection)) {
+            p.cancel('Setup cancelled.');
+            process.exit(0);
+        }
+        useDetectedValues = confirmDetection;
+    }
+    else if (triageResult) {
+        if (detectedType || detectedTech.length > 0) {
+            p.note(formatDetectionResults(detectedType, detectedTech, triageResult), 'Partial Detection (will be used as defaults)');
+        }
+    }
+    let projectInfo;
+    if (useDetectedValues) {
+        projectInfo = {
+            projectType: detectedType,
+            techStack: detectedTech,
+        };
+        p.log.success('Using auto-detected configuration.');
+    }
+    else {
+        projectInfo = await p.group({
+            projectType: () => p.select({
+                message: 'What type of WordPress project is this?',
+                options: [
+                    { value: 'plugin', label: 'Plugin' },
+                    { value: 'theme', label: 'Theme' },
+                    { value: 'block-theme', label: 'Block Theme' },
+                    { value: 'site', label: 'Full Site / Multisite' },
+                    { value: 'blocks', label: 'Gutenberg Blocks' },
+                    { value: 'other', label: 'Other / Mixed' },
+                    { value: 'unsure', label: "I'm not sure" },
+                ],
+                initialValue: detectedType || undefined,
+            }),
+            techStack: () => p.multiselect({
+                message: 'Select technologies (or skip if unsure):',
+                options: [
+                    { value: 'gutenberg', label: 'Gutenberg Blocks', hint: 'block.json, @wordpress/blocks' },
+                    { value: 'interactivity', label: 'Interactivity API', hint: 'data-wp-* directives' },
+                    { value: 'rest-api', label: 'REST API', hint: 'Custom endpoints' },
+                    { value: 'wpcli', label: 'WP-CLI', hint: 'Custom commands' },
+                    { value: 'composer', label: 'Composer', hint: 'PHP dependencies' },
+                    { value: 'npm', label: 'npm/pnpm', hint: 'JS build process' },
+                    { value: 'phpstan', label: 'PHPStan', hint: 'Static analysis' },
+                    { value: 'playground', label: 'WordPress Playground', hint: 'Testing/demo' },
+                ],
+                initialValues: detectedTech.length > 0 ? detectedTech : undefined,
+                required: false,
+            }),
+        }, {
+            onCancel: () => {
+                p.cancel('Setup cancelled.');
+                process.exit(0);
+            },
+        });
+        if (projectInfo.projectType === 'unsure') {
+            projectInfo.projectType = 'other';
+            p.log.info('Using "other" as project type. You can adjust AGENTS.md later.');
+        }
+    }
+    const customizeAgents = await p.confirm({
+        message: 'Customize AGENTS.md with project details?',
+        initialValue: true,
+    });
+    if (p.isCancel(customizeAgents)) {
+        p.cancel('Setup cancelled.');
+        process.exit(0);
+    }
+    if (customizeAgents) {
+        try {
+            let agentsContent = fs.readFileSync(agentsPath, 'utf-8');
+            agentsContent = agentsContent.replace(/\*\*Tooling\*\*: .*/, `**Tooling**: ${projectInfo.techStack.includes('composer') ? 'Composer for PHP' : ''}${projectInfo.techStack.includes('npm') ? `, ${detectedPackageManager} for JS` : ''}.`);
+            fs.writeFileSync(agentsPath, agentsContent, 'utf-8');
+            p.log.success('Updated AGENTS.md');
+        }
+        catch (err) {
+            p.log.warn(`Could not update AGENTS.md: ${err.message}`);
+        }
+    }
+    // Workflow instructions
+    if (fs.existsSync(platformInstructionsPath)) {
+        const customizeWorkflow = await p.confirm({
+            message: 'Open workflow instructions for manual editing?',
+            initialValue: false,
+        });
+        if (!p.isCancel(customizeWorkflow) && customizeWorkflow) {
+            p.note(`Edit: ${platformInstructionsPath}\n\nAdd your project-specific:\n- Coding standards\n- Git workflow\n- Testing procedures\n- Deployment steps`, 'Workflow Instructions');
+        }
+    }
+    const promptsFolder = path.join(targetDir, platformFolder, 'prompts');
+    p.note(`✓ Kit installed and configured\n\n` +
+        `Next steps:\n` +
+        `1. Review ${agentsPath}\n` +
+        `2. Customize ${promptsFolder}/ for your domain\n` +
+        `3. Test with: ${projectInfo.projectType === 'plugin' ? '"Create a new settings page"' : '"Generate a block variation"'}\n` +
+        `4. Adjust skills loading in AGENTS.md as needed`, 'Setup Complete');
+    p.outro('Your WordPress project is now AI-ready!');
+});

package/dist/commands/sync-skills.js

@@ -0,0 +1,70 @@
+import { Command } from 'commander';
+import fs from 'node:fs';
+import path from 'node:path';
+import { run } from '../utils/run.js';
+const OFFICIAL_SKILLS_REPO_URL = 'https://github.com/WordPress/agent-skills.git';
+const DEFAULT_SKILLS_REF = 'trunk';
+/**
+ * Command to sync skills from the official WordPress agent-skills repository.
+ * Can checkout a specific branch or tag.
+ */
+export const syncSkillsCommand = new Command('sync-skills')
+    .description('Sync skills from the official WordPress agent-skills repository')
+    .argument('[ref]', 'Branch or tag to checkout', DEFAULT_SKILLS_REF)
+    .action((refPassed) => {
+    // Check for custom URL args - simplistic check
+    if (/^(https?:\/\/|git@)/i.test(refPassed)) {
+        console.error('Custom skills repository URLs are not supported. This script syncs from the official WordPress/agent-skills repo only.');
+        process.exit(2);
+    }
+    // Check if refPassed might contain URL (same check as above) or empty string
+    const ref = refPassed || DEFAULT_SKILLS_REF;
+    const repoRoot = process.cwd();
+    const submodulePath = path.join('vendor', 'wp-agent-skills');
+    const vendorSkillsDir = path.join(repoRoot, submodulePath);
+    const submoduleGitDir = path.join(vendorSkillsDir, '.git');
+    // Clone or update the skills repo (not as a submodule since it's gitignored)
+    if (!fs.existsSync(submoduleGitDir)) {
+        fs.mkdirSync(path.join(repoRoot, 'vendor'), { recursive: true });
+        console.log(`Cloning ${OFFICIAL_SKILLS_REPO_URL} into ${submodulePath}...`);
+        run('git', ['clone', OFFICIAL_SKILLS_REPO_URL, submodulePath], repoRoot);
+    }
+    else {
+        console.log(`Updating existing skills repo at ${submodulePath}...`);
+        run('git', ['fetch', '--all', '--tags'], vendorSkillsDir);
+    }
+    // Checkout the specified ref
+    if (ref) {
+        run('git', ['checkout', ref], vendorSkillsDir);
+        run('git', ['pull', 'origin', ref], vendorSkillsDir);
+    }
+    const targetSkills = path.join(repoRoot, '.github', 'skills');
+    const upstreamBuildScript = path.join(vendorSkillsDir, 'shared', 'scripts', 'skillpack-build.mjs');
+    const upstreamInstallScript = path.join(vendorSkillsDir, 'shared', 'scripts', 'skillpack-install.mjs');
+    if (fs.existsSync(upstreamBuildScript) && fs.existsSync(upstreamInstallScript)) {
+        if (fs.existsSync(targetSkills)) {
+            fs.rmSync(targetSkills, { recursive: true, force: true });
+        }
+        fs.mkdirSync(path.join(repoRoot, '.github'), { recursive: true });
+        run('node', ['shared/scripts/skillpack-build.mjs', '--clean', '--targets=vscode'], vendorSkillsDir);
+        run('node', ['shared/scripts/skillpack-install.mjs', `--dest=${repoRoot}`, '--targets=vscode', '--from=dist', '--mode=replace'], vendorSkillsDir);
+        console.log(`Synced skills into: ${targetSkills}`);
+        console.log(`Skills source: ${OFFICIAL_SKILLS_REPO_URL}${ref ? ` @ ${ref}` : ''}`);
+        console.log('Sync method: upstream skillpack-build.mjs + skillpack-install.mjs');
+        // No process.exit here, let commander handle exit or fallthrough unless explicit stop
+        return;
+    }
+    const sourceSkills = path.join(vendorSkillsDir, '.github', 'skills');
+    if (!fs.existsSync(sourceSkills)) {
+        console.error(`Could not find upstream skills directory at: ${sourceSkills}`);
+        process.exit(1);
+    }
+    if (fs.existsSync(targetSkills)) {
+        fs.rmSync(targetSkills, { recursive: true, force: true });
+    }
+    fs.mkdirSync(path.join(repoRoot, '.github'), { recursive: true });
+    fs.cpSync(sourceSkills, targetSkills, { recursive: true });
+    console.log(`Synced skills into: ${targetSkills}`);
+    console.log(`Skills source: ${OFFICIAL_SKILLS_REPO_URL}${ref ? ` @ ${ref}` : ''}`);
+    console.log('Sync method: fallback direct copy from .github/skills');
+});

package/dist/lib/installer.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { PACKAGE_ROOT } from '../utils/paths.js';
+/**
+ * Platform-specific folder names
+ */
+export const PLATFORM_FOLDERS = {
+    github: '.github',
+    cursor: '.cursor',
+    claude: '.claude',
+    agent: '.agent',
+    pi: '.pi/agent',
+};
+/**
+ * Installs the WordPress Agent Kit into the specified directory for a given platform.
+ * Copies the platform-specific folder and AGENTS.md template.
+ *
+ * @param {string} targetDir - The directory where the kit should be installed.
+ * @param {Platform} platform - The target platform (github, cursor, claude, agent)
+ * @returns {Promise<void>}
+ */
+export async function installKit(targetDir, platform = 'github') {
+    const platformFolder = PLATFORM_FOLDERS[platform];
+    console.log(`Installing WordPress Agent Kit (${platform}) into: ${targetDir}`);
+    if (!fs.existsSync(targetDir)) {
+        fs.mkdirSync(targetDir, { recursive: true });
+    }
+    const templatePath = path.join(PACKAGE_ROOT, 'AGENTS.template.md');
+    const agentsPath = path.join(PACKAGE_ROOT, 'AGENTS.md');
+    const sourceGithub = path.join(PACKAGE_ROOT, '.github');
+    // Copy platform-specific folder
+    const targetPlatform = path.join(targetDir, platformFolder);
+    if (fs.existsSync(targetPlatform)) {
+        fs.rmSync(targetPlatform, { recursive: true, force: true });
+    }
+    if (fs.existsSync(sourceGithub)) {
+        fs.cpSync(sourceGithub, targetPlatform, { recursive: true });
+    }
+    else {
+        throw new Error('Could not find source .github directory.');
+    }
+    // Copy AGENTS.md
+    const targetAgentsTemplate = path.join(targetDir, 'AGENTS.template.md');
+    if (fs.existsSync(templatePath)) {
+        fs.copyFileSync(templatePath, targetAgentsTemplate);
+    }
+    const targetAgents = path.join(targetDir, 'AGENTS.md');
+    if (!fs.existsSync(targetAgents)) {
+        if (fs.existsSync(templatePath)) {
+            fs.copyFileSync(templatePath, targetAgents);
+        }
+        else if (fs.existsSync(agentsPath)) {
+            fs.copyFileSync(agentsPath, targetAgents);
+        }
+    }
+}

package/dist/lib/triage-mapper.js

@@ -0,0 +1,98 @@
+/**
+ * Maps triage detection results to setup configuration
+ */
+/**
+ * Maps project.primary to setup's project type options
+ * @param {string} primary - The primary project type from triage
+ * @returns {string|null} - Mapped project type or null
+ */
+export function mapProjectType(primary) {
+    const typeMap = {
+        'wp-block-theme': 'block-theme',
+        'wp-block-plugin': 'blocks',
+        'wp-plugin': 'plugin',
+        'wp-mu-plugin': 'plugin',
+        'wp-theme': 'theme',
+        'wp-site': 'site',
+        'wp-core': 'other',
+        'gutenberg': 'blocks',
+        'unknown': null,
+    };
+    return typeMap[primary] || null;
+}
+/**
+ * Maps triage signals and tooling to tech stack array
+ * @param {object} triageResult - Full triage result object
+ * @returns {string[]} - Array of tech stack values
+ */
+export function mapTechStack(triageResult) {
+    const techStack = [];
+    const { signals, tooling } = triageResult;
+    // Map signals
+    if (signals.blockJsonFiles && signals.blockJsonFiles.length > 0) {
+        techStack.push('gutenberg');
+    }
+    if (signals.usesInteractivityApi) {
+        techStack.push('interactivity');
+    }
+    if (signals.usesWpCli) {
+        techStack.push('wpcli');
+    }
+    if (signals.usesRestApi) {
+        techStack.push('rest-api');
+    }
+    // Map tooling
+    if (tooling.php?.hasComposerJson) {
+        techStack.push('composer');
+    }
+    if (tooling.php?.hasPhpStan) {
+        techStack.push('phpstan');
+    }
+    if (tooling.node?.hasPackageJson) {
+        techStack.push('npm');
+    }
+    // Check for playground blueprint
+    if (signals.hasPlaygroundBlueprint) {
+        techStack.push('playground');
+    }
+    return techStack;
+}
+/**
+ * Checks if detection has enough confidence to skip questions
+ * @param {string|null} detectedType - Detected project type
+ * @param {string[]} detectedTech - Detected tech stack
+ * @returns {boolean} - True if confident enough
+ */
+export function hasConfidentDetection(detectedType, detectedTech) {
+    return detectedType !== null && detectedType !== 'other';
+}
+/**
+ * Formats detection results for display
+ * @param {string|null} detectedType - Detected project type
+ * @param {string[]} detectedTech - Detected tech stack
+ * @param {object} triageResult - Full triage result for additional notes
+ * @returns {string} - Formatted string for display
+ */
+export function formatDetectionResults(detectedType, detectedTech, triageResult) {
+    const typeLabels = {
+        'plugin': 'WordPress Plugin',
+        'theme': 'WordPress Theme',
+        'block-theme': 'Block Theme',
+        'site': 'Full Site / Multisite',
+        'blocks': 'Gutenberg Blocks',
+        'other': 'Other / Mixed',
+    };
+    const techLabels = {
+        'gutenberg': 'Blocks',
+        'interactivity': 'Interactivity API',
+        'wpcli': 'WP-CLI',
+        'rest-api': 'REST API',
+        'composer': 'Composer',
+        'phpstan': 'PHPStan',
+        'npm': 'npm/package.json',
+        'playground': 'Playground',
+    };
+    const typeLabel = detectedType ? typeLabels[detectedType] : 'Unknown';
+    const techList = detectedTech.map(t => techLabels[t] || t).join(', ');
+    return `Project Type: ${typeLabel}\nTech Stack: ${techList}`;
+}

package/dist/utils/paths.js

@@ -0,0 +1,12 @@
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+// Get the root directory of the package (where package.json lives)
+// When running from src (ts-node), it's ../
+// When running from dist (node), it's ../
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * The absolute path to the root directory of the package.
+ * Resolves to the directory containing package.json.
+ */
+export const PACKAGE_ROOT = path.resolve(__dirname, '../../');

package/dist/utils/run.js

@@ -0,0 +1,20 @@
+import { spawnSync } from 'node:child_process';
+/**
+ * Executes a shell command synchronously and exits the process if it fails.
+ *
+ * @param {string} command - The command to execute (e.g., 'npm', 'git').
+ * @param {string[]} args - An array of arguments for the command.
+ * @param {string} [cwd] - The current working directory for the command. Defaults to process.cwd().
+ * @returns {void}
+ */
+export function run(command, args, cwd = process.cwd()) {
+    const result = spawnSync(command, args, {
+        cwd,
+        stdio: 'inherit',
+        shell: process.platform === 'win32'
+    });
+    if (result.status !== 0) {
+        console.error(`Command failed with status ${result.status}: ${command} ${args.join(' ')}`);
+        process.exit(result.status || 1);
+    }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "wordpress-agent-kit",
+  "version": "0.2.1",
+  "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)",
+  "homepage": "https://brodeur.me",
+  "private": false,
+  "type": "module",
+  "keywords": [
+    "wordpress",
+    "agents",
+    "agents-md",
+    "agent-skills",
+    "ai-coding",
+    "copilot"
+  ],
+  "engines": {
+    "node": ">=20.18"
+  },
+  "bin": {
+    "wp-agent-kit": "dist/cli.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.8.2",
+    "commander": "^13.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@types/node": "^22.10.1",
+    "@vitest/coverage-v8": "^2.1.8",
+    "eslint": "^9.16.0",
+    "prettier": "^3.4.1",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.18.0",
+    "vitest": "^2.1.8",
+    "@earendil-works/pi-coding-agent": "^0.78.1"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc",
+    "check": "tsc --noEmit",
+    "lint": "eslint src/ --fix",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "install:kit": "tsx src/cli.ts install",
+    "sync:skills": "tsx src/cli.ts sync-skills",
+    "setup": "tsx src/cli.ts setup",
+    "playground": "tsx src/cli.ts playground",
+    "build:bundles": "tsx scripts/build-bundles.ts"
+  }
+}