wordpress-agent-kit 0.4.0 → 0.6.0

package/dist/lib/api.js

@@ -267,21 +267,35 @@ export async function syncSkillsApi(options = {}) {
             // Merge custom skills (skills-custom/) — these are not part of the upstream
             // WordPress/agent-skills repo and survive upstream syncs.
             const customSkillsDir = path.join(PACKAGE_ROOT, 'skills-custom');
+            let customMerged = 0;
             if (fs.existsSync(customSkillsDir)) {
                 for (const skillName of fs.readdirSync(customSkillsDir)) {
                     const src = path.join(customSkillsDir, skillName);
                     const dest = path.join(targetSkills, skillName);
                     if (fs.statSync(src).isDirectory()) {
+                        const isNew = !fs.existsSync(dest);
                         fs.cpSync(src, dest, { recursive: true });
-                        skillsSynced++;
+                        if (isNew) {
+                            skillsSynced++;
+                        }
+                        customMerged++;
                     }
                 }
             }
-            return { success: true, skillsSynced, method };
+            // Copy synced skills to the canonical .agents/skills/ directory
+            // (AgentSkills.io convention — the pi.skills path in package.json points here).
+            const canonicalSkills = path.join(PACKAGE_ROOT, '.agents', 'skills');
+            if (fs.existsSync(canonicalSkills)) {
+                fs.rmSync(canonicalSkills, { recursive: true, force: true });
+            }
+            fs.mkdirSync(path.join(PACKAGE_ROOT, '.agents'), { recursive: true });
+            fs.cpSync(targetSkills, canonicalSkills, { recursive: true });
+            return { success: true, skillsSynced, customMerged, method };
         });
         return formatter.success({
             targetDir,
             skillsSynced: result.skillsSynced,
+            customMerged: result.customMerged,
             sourceUrl: 'https://github.com/WordPress/agent-skills.git',
             ref,
             durationMs: Date.now() - startTime,
@@ -334,7 +348,13 @@ function dryRunSyncSkills(targetDir, ref) {
     actions.push({
         type: 'create',
         target: targetSkills,
-        description: 'Install synced skills',
+        description: 'Install synced skills to .github/skills (sync buffer), then copy to .agents/skills (canonical)',
+    });
+    const canonicalSkills = path.join(targetDir, '.agents', 'skills');
+    actions.push({
+        type: 'create',
+        target: canonicalSkills,
+        description: 'Copy synced skills to .agents/skills (canonical, AgentSkills.io convention)',
     });
     return new OutputFormatter('json', 'sync-skills', '0.0.0').success({
         wouldExecute: true,
@@ -342,6 +362,7 @@ function dryRunSyncSkills(targetDir, ref) {
         summary: {
             targetDir,
             skillsSynced: 0,
+            customMerged: 0,
             sourceUrl: 'https://github.com/WordPress/agent-skills.git',
             ref,
             durationMs: 0,
@@ -356,9 +377,13 @@ export async function runTriageApi(options) {
     const formatter = new OutputFormatter('json', 'triage', '0.0.0');
     const { targetDir, platform = 'github' } = options;
     try {
-        const platformFolder = getPlatformFolder(platform);
         const triageScriptPaths = [
-            path.join(targetDir, platformFolder, 'skills/wp-project-triage/scripts/detect_wp_project.mjs'),
+            // Canonical location (AgentSkills.io convention)
+            path.join(targetDir, '.agents', 'skills/wp-project-triage/scripts/detect_wp_project.mjs'),
+            // Legacy platform-specific location
+            path.join(targetDir, getPlatformFolder(platform), 'skills/wp-project-triage/scripts/detect_wp_project.mjs'),
+            // Source repo
+            path.join(PACKAGE_ROOT, '.agents', 'skills/wp-project-triage/scripts/detect_wp_project.mjs'),
             path.join(PACKAGE_ROOT, 'vendor/wp-agent-skills/skills/wp-project-triage/scripts/detect_wp_project.mjs'),
         ];
         const triageScriptPath = triageScriptPaths.find((p) => fs.existsSync(p));
@@ -530,6 +555,141 @@ function getInstalledSummary(targetDir, platform) {
     }
     return summary;
 }
+/**
+ * Detect and optionally remove orphaned skills from a target installation.
+ * Compares the skills in the target platform directory against the source kit
+ * (upstream .agents/skills + skills-custom/) and identifies skills that exist
+ * in the target but not in the source.
+ */
+export async function cleanSkillsApi(options) {
+    const startTime = Date.now();
+    const formatter = new OutputFormatter('json', 'clean-skills', '0.0.0');
+    const { targetDir, platform, dryRun = false, remove = false } = options;
+    try {
+        // Canonical skills come from .agents/skills/ (AgentSkills.io convention)
+        // with skills-custom/ as supplemental source for custom skills.
+        const canonicalSkillsDir = path.join(PACKAGE_ROOT, '.agents', 'skills');
+        const customSkillsDir = path.join(PACKAGE_ROOT, 'skills-custom');
+        const targetSkillsDir = path.join(targetDir, '.agents', 'skills');
+        // Build set of canonical skill names (upstream + custom)
+        const canonicalSkills = new Set();
+        if (fs.existsSync(canonicalSkillsDir)) {
+            for (const entry of fs.readdirSync(canonicalSkillsDir)) {
+                const entryPath = path.join(canonicalSkillsDir, entry);
+                if (fs.statSync(entryPath).isDirectory()) {
+                    canonicalSkills.add(entry);
+                }
+            }
+        }
+        if (fs.existsSync(customSkillsDir)) {
+            for (const entry of fs.readdirSync(customSkillsDir)) {
+                const entryPath = path.join(customSkillsDir, entry);
+                if (fs.statSync(entryPath).isDirectory()) {
+                    canonicalSkills.add(entry);
+                }
+            }
+        }
+        // Find orphaned skills in target .agents/skills/
+        const orphanedSkills = [];
+        if (fs.existsSync(targetSkillsDir)) {
+            for (const entry of fs.readdirSync(targetSkillsDir)) {
+                const entryPath = path.join(targetSkillsDir, entry);
+                if (fs.statSync(entryPath).isDirectory() && !canonicalSkills.has(entry)) {
+                    orphanedSkills.push(entry);
+                }
+            }
+        }
+        // Detect legacy skill directories (platform-specific skills/ dirs)
+        const platformFolder = getPlatformFolder(platform);
+        const legacySkillsDir = path.join(targetDir, platformFolder, 'skills');
+        const legacySkillDirs = [];
+        if (fs.existsSync(legacySkillsDir)) {
+            legacySkillDirs.push(legacySkillsDir);
+        }
+        // Also check .github/skills for github platform (common legacy location)
+        if (platform !== 'github') {
+            const githubSkills = path.join(targetDir, '.github', 'skills');
+            if (fs.existsSync(githubSkills)) {
+                legacySkillDirs.push(githubSkills);
+            }
+        }
+        // Migrate legacy skills to .agents/skills/ and remove legacy dirs
+        const migratedSkills = [];
+        if (remove && !dryRun && legacySkillDirs.length > 0) {
+            for (const legacyDir of legacySkillDirs) {
+                for (const entry of fs.readdirSync(legacyDir)) {
+                    const entryPath = path.join(legacyDir, entry);
+                    if (!fs.statSync(entryPath).isDirectory())
+                        continue;
+                    const destPath = path.join(targetSkillsDir, entry);
+                    if (!fs.existsSync(destPath)) {
+                        fs.mkdirSync(path.dirname(destPath), { recursive: true });
+                        fs.cpSync(entryPath, destPath, { recursive: true });
+                        migratedSkills.push(entry);
+                    }
+                }
+                // Remove the legacy skills directory
+                fs.rmSync(legacyDir, { recursive: true, force: true });
+            }
+        }
+        // Remove orphans if requested
+        const removedSkills = [];
+        if (remove && !dryRun) {
+            for (const orphan of orphanedSkills) {
+                const orphanPath = path.join(targetSkillsDir, orphan);
+                fs.rmSync(orphanPath, { recursive: true, force: true });
+                removedSkills.push(orphan);
+            }
+        }
+        const _durationMs = Date.now() - startTime;
+        if (dryRun) {
+            const actions = orphanedSkills.map((s) => ({
+                type: 'delete',
+                target: path.join('.agents', 'skills', s),
+                description: `Remove orphaned skill: ${s}`,
+            }));
+            for (const legacyDir of legacySkillDirs) {
+                actions.push({
+                    type: 'delete',
+                    target: legacyDir,
+                    description: `Migrate and remove legacy skill directory: ${path.relative(targetDir, legacyDir)}`,
+                });
+            }
+            return formatter.success({
+                wouldExecute: true,
+                actions,
+                summary: {
+                    targetDir,
+                    platform,
+                    orphanedSkills,
+                    removedSkills: [],
+                    legacySkillDirs,
+                    migratedSkills: [],
+                    dryRun: true,
+                },
+            });
+        }
+        return formatter.success({
+            targetDir,
+            platform,
+            orphanedSkills,
+            removedSkills,
+            legacySkillDirs,
+            migratedSkills,
+            dryRun: false,
+        });
+    }
+    catch (error) {
+        const err = error;
+        return formatter.fail({
+            code: err.code || 'CLEAN_FAILED',
+            message: err.message || 'Clean failed',
+            exitCode: err.exitCode ?? ExitCode.ERROR,
+            details: { platform, targetDir },
+        });
+    }
+}
 export { ExitCode } from '../utils/exit-codes.js';
 export { OutputFormatter, createFormatter, parseOutputFormat } from '../utils/output.js';
 export { computeChanges, isKitInstalled, loadManifest, updateKit } from './updater.js';
+export { bootstrapApi } from './bootstrap.js';

package/dist/lib/bootstrap.js

@@ -0,0 +1,352 @@
+/**
+ * Bootstrap API — detects WordPress project structure and scaffolds
+ * the full wp-agent-kit system (agent kit, Composer, WP-CLI, Playground,
+ * WP Engine CI/CD, git hooks). Supports single plugins/themes and monorepos.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { ExitCode } from '../utils/exit-codes.js';
+import { OutputFormatter } from '../utils/output.js';
+import { PACKAGE_ROOT } from '../utils/paths.js';
+import { installKit } from './installer.js';
+// ── Detection ─────────────────────────────────────────────────────────────
+/**
+ * Run the detect-structure.mjs probe script and return the parsed result.
+ */
+export function detectStructure(targetDir) {
+    const detectScript = path.join(PACKAGE_ROOT, '.agents', 'skills', 'wp-bootstrap', 'scripts', 'detect-structure.mjs');
+    if (!fs.existsSync(detectScript)) {
+        // Fallback: minimal detection without the full script
+        return minimalDetect(targetDir);
+    }
+    const result = spawnSync('node', [detectScript, targetDir], {
+        encoding: 'utf-8',
+        cwd: targetDir,
+    });
+    if (result.status !== 0) {
+        return minimalDetect(targetDir);
+    }
+    try {
+        return JSON.parse(result.stdout.trim());
+    }
+    catch {
+        return minimalDetect(targetDir);
+    }
+}
+/** Minimal structure detection without the full probe script */
+function minimalDetect(targetDir) {
+    const exists = (...parts) => fs.existsSync(path.join(targetDir, ...parts));
+    const pm = exists('pnpm-lock.yaml')
+        ? 'pnpm'
+        : exists('yarn.lock')
+            ? 'yarn'
+            : exists('package.json')
+                ? 'npm'
+                : null;
+    return {
+        repoRoot: targetDir,
+        isMonorepo: false,
+        packageManager: pm,
+        jsWorkspaces: [],
+        wpPackages: [],
+        wpRoot: exists('wp-config.php') ? '.' : null,
+        wpRootExists: exists('wp-config.php'),
+        playgroundOnly: !exists('wp-config.php'),
+        wpeRemotes: [],
+        hasWpeRemote: false,
+        php: {
+            hasComposer: exists('composer.json'),
+            hasPhpcs: exists('vendor/bin/phpcs'),
+            hasWpcs: false,
+            hasPhpstan: exists('vendor/bin/phpstan'),
+            hasPhpstanWp: false,
+            hasPest: false,
+            phpcsConfig: exists('phpcs.xml.dist') ? 'phpcs.xml.dist' : null,
+            phpstanConfig: exists('phpstan.neon.dist') ? 'phpstan.neon.dist' : null,
+            composerScripts: [],
+        },
+        js: {
+            hasBiome: exists('biome.json'),
+            biomeVersion: null,
+            hasEslint: exists('eslint.config.mjs') || exists('.eslintrc.js'),
+            hasPrettier: exists('.prettierrc'),
+            hasVitest: false,
+            hasJest: false,
+            hasPlaywright: exists('playwright.config.ts') || exists('playwright.config.js'),
+            hasWpScripts: false,
+            rootScripts: [],
+        },
+        playground: {
+            hasPlayground: exists('tools/playground') || exists('playground'),
+            blueprints: [],
+            scripts: [],
+            hasWpEnv: exists('.wp-env.json'),
+        },
+        satispress: { configured: false, url: null, hasAuthJson: false },
+        wpackagist: false,
+        gitHooks: exists('.githooks') ? '.githooks' : exists('.husky') ? '.husky' : null,
+        hasAgentKit: exists('.wp-agent-kit-manifest.github.json') || exists('.agents', 'skills'),
+        hasAgentsDir: exists('.agents'),
+        hasAgentsMd: exists('AGENTS.md'),
+        gitBranch: null,
+        gitRemotes: [],
+    };
+}
+// ── Scaffolding helpers ────────────────────────────────────────────────────
+function writeIfMissing(filePath, content, dryRun) {
+    if (fs.existsSync(filePath))
+        return false;
+    if (!dryRun) {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, content, 'utf-8');
+    }
+    return true;
+}
+function scaffoldWpCliYml(targetDir, structure, wpeEnvironments, dryRun) {
+    const wpCliPath = path.join(targetDir, 'wp-cli.yml');
+    if (fs.existsSync(wpCliPath))
+        return [];
+    const localPath = structure.wpRoot && structure.wpRoot !== '.' ? `path: ./${structure.wpRoot}\n\n` : '';
+    const prod = wpeEnvironments?.production;
+    const staging = wpeEnvironments?.staging;
+    const dev = wpeEnvironments?.development;
+    const content = [
+        '# wp-cli.yml — WP-CLI targeting. Commit to repo.',
+        '# Get exact git push URLs from: https://my.wpengine.com/installs/<ENV>/git_push',
+        '',
+        localPath,
+        prod
+            ? `@production:\n  ssh: ${prod}@${prod}.ssh.wpengine.net\n  path: /home/wpe-user/sites/${prod}\n`
+            : '',
+        staging
+            ? `\n@staging:\n  ssh: ${staging}@${staging}.ssh.wpengine.net\n  path: /home/wpe-user/sites/${staging}\n`
+            : '',
+        dev
+            ? `\n@development:\n  ssh: ${dev}@${dev}.ssh.wpengine.net\n  path: /home/wpe-user/sites/${dev}\n`
+            : '',
+    ].join('');
+    if (writeIfMissing(wpCliPath, content, dryRun)) {
+        return ['wp-cli.yml'];
+    }
+    return [];
+}
+function scaffoldGitHooks(targetDir, dryRun) {
+    const hooksDir = path.join(targetDir, '.githooks');
+    const prePush = path.join(hooksDir, 'pre-push');
+    const readme = path.join(hooksDir, 'README.md');
+    const created = [];
+    const prePushContent = `#!/usr/bin/env bash
+# .githooks/pre-push — CI gate before every push.
+# Activate once: git config core.hooksPath .githooks
+# Generated by wp-agent-kit bootstrap.
+set -uo pipefail
+root="$(git rev-parse --show-toplevel)"
+cd "$root"
+
+# Run the CI gate (PHP + JS/TS)
+GATE_SCRIPT=".agents/skills/wp-bootstrap/scripts/ci-gate.sh"
+if [ -f "$GATE_SCRIPT" ]; then
+  bash "$GATE_SCRIPT" || exit 1
+else
+  echo "⚠  CI gate script not found at $GATE_SCRIPT" >&2
+  echo "   Run wp-agent-kit install to set up .agents/skills/" >&2
+fi
+`;
+    const readmeContent = `# Git hooks (versioned)
+
+Activate once per clone:
+\`\`\`bash
+git config core.hooksPath .githooks
+chmod +x .githooks/pre-push
+\`\`\`
+Or run: \`pnpm run setup\` / \`bash tools/setup.sh\` if that exists.
+
+## What runs
+
+- **pre-push**: PHP gate (php -l + phpcs + phpstan) + JS gate (biome check).
+  Fix failures with \`composer fix && composer lint\` (PHP) or \`npx biome check --write .\` (JS).
+  --no-verify is not allowed on deploy branches; CI will catch it anyway.
+`;
+    if (!fs.existsSync(hooksDir) && !dryRun) {
+        fs.mkdirSync(hooksDir, { recursive: true });
+    }
+    if (writeIfMissing(prePush, prePushContent, dryRun)) {
+        if (!dryRun)
+            fs.chmodSync(prePush, 0o755);
+        created.push('.githooks/pre-push');
+    }
+    if (writeIfMissing(readme, readmeContent, dryRun)) {
+        created.push('.githooks/README.md');
+    }
+    return created;
+}
+function scaffoldSetupSh(targetDir, dryRun) {
+    const toolsDir = path.join(targetDir, 'tools');
+    const setupSh = path.join(toolsDir, 'setup.sh');
+    if (fs.existsSync(setupSh))
+        return [];
+    const content = `#!/usr/bin/env bash
+# tools/setup.sh — one-command dev setup. Idempotent: safe to re-run.
+# Generated by wp-agent-kit bootstrap.
+set -uo pipefail
+root="$(cd "$(dirname "$0")/.." && pwd)"
+bash "$root/.agents/skills/wp-bootstrap/scripts/bootstrap.sh" "$@"
+`;
+    if (writeIfMissing(setupSh, content, dryRun)) {
+        if (!dryRun)
+            fs.chmodSync(setupSh, 0o755);
+        return ['tools/setup.sh'];
+    }
+    return [];
+}
+function scaffoldBootstrapConfig(targetDir, structure, options, dryRun) {
+    const configPath = path.join(targetDir, 'wp-bootstrap.config.json');
+    if (fs.existsSync(configPath))
+        return [];
+    const config = {
+        packageManager: options.packageManager ?? structure.packageManager ?? 'npm',
+        jsWorkspaces: structure.jsWorkspaces,
+        phpDirs: ['.', ...structure.wpPackages.filter((p) => p.hasComposer).map((p) => p.path)],
+        hooksDir: '.githooks',
+        wpPackages: structure.wpPackages.map((p) => ({
+            path: p.path,
+            type: p.type,
+            slug: p.slug,
+            ...(p.mainFile ? { mainFile: p.mainFile } : {}),
+        })),
+        ...(structure.wpeRemotes.length > 0 || options.wpeEnvironments
+            ? {
+                wpeEnvironments: {
+                    ...(options.wpeEnvironments?.production
+                        ? {
+                            production: { install: options.wpeEnvironments.production },
+                        }
+                        : {}),
+                    ...(options.wpeEnvironments?.staging
+                        ? {
+                            staging: { install: options.wpeEnvironments.staging },
+                        }
+                        : {}),
+                    ...(options.wpeEnvironments?.development
+                        ? {
+                            development: { install: options.wpeEnvironments.development },
+                        }
+                        : {}),
+                },
+            }
+            : {}),
+    };
+    if (writeIfMissing(configPath, `${JSON.stringify(config, null, 2)}
+`, dryRun)) {
+        return ['wp-bootstrap.config.json'];
+    }
+    return [];
+}
+// ── Main API ───────────────────────────────────────────────────────────────
+export async function bootstrapApi(options) {
+    const formatter = new OutputFormatter('json', 'bootstrap', '0.0.0');
+    const { targetDir, platform = 'github', detectOnly = false, dryRun = false, skipInstall = false, } = options;
+    try {
+        // 1. Detect structure
+        const structure = detectStructure(targetDir);
+        if (!structure) {
+            return formatter.fail({
+                code: 'DETECT_FAILED',
+                message: 'Failed to detect project structure',
+                exitCode: ExitCode.ERROR,
+            });
+        }
+        // Apply overrides
+        if (options.wpRoot)
+            structure.wpRoot = options.wpRoot;
+        if (options.packageManager)
+            structure.packageManager = options.packageManager;
+        if (detectOnly) {
+            return formatter.success({
+                structure,
+                detectOnly: true,
+                actions: [],
+                filesCreated: [],
+                dryRun,
+            });
+        }
+        const actions = [];
+        const filesCreated = [];
+        // 2. Install agent kit
+        if (!skipInstall && !structure.hasAgentKit) {
+            if (!dryRun) {
+                installKit(targetDir, platform, { safe: true, backup: false });
+            }
+            actions.push(`✅ wp-agent-kit installed (platform: ${platform})`);
+            filesCreated.push('.agents/skills/', `${platform === 'github' ? '.github' : `.${platform}`}/`);
+        }
+        else if (structure.hasAgentKit) {
+            actions.push('✓ wp-agent-kit already installed');
+        }
+        // 3. Generate wp-cli.yml
+        const wpeEnvs = options.wpeEnvironments;
+        const hasWpeConfig = wpeEnvs?.production || wpeEnvs?.staging || wpeEnvs?.development;
+        if (hasWpeConfig || structure.wpRoot) {
+            const created = scaffoldWpCliYml(targetDir, structure, wpeEnvs, dryRun);
+            if (created.length > 0) {
+                actions.push('✅ wp-cli.yml created');
+                filesCreated.push(...created);
+            }
+            else {
+                actions.push('✓ wp-cli.yml already exists');
+            }
+        }
+        // 4. Git hooks
+        const hookFiles = scaffoldGitHooks(targetDir, dryRun);
+        if (hookFiles.length > 0) {
+            actions.push('✅ .githooks/pre-push created');
+            filesCreated.push(...hookFiles);
+            if (!dryRun) {
+                // Activate hooks
+                spawnSync('git', ['config', 'core.hooksPath', '.githooks'], { cwd: targetDir });
+            }
+            actions.push('✅ git config core.hooksPath .githooks');
+        }
+        // 5. tools/setup.sh
+        const setupFiles = scaffoldSetupSh(targetDir, dryRun);
+        if (setupFiles.length > 0) {
+            actions.push('✅ tools/setup.sh created');
+            filesCreated.push(...setupFiles);
+        }
+        // 6. wp-bootstrap.config.json
+        const configFiles = scaffoldBootstrapConfig(targetDir, structure, options, dryRun);
+        if (configFiles.length > 0) {
+            actions.push('✅ wp-bootstrap.config.json created');
+            filesCreated.push(...configFiles);
+        }
+        // 7. Report what still needs manual setup
+        if (!structure.php.hasComposer) {
+            actions.push('⚠  composer.json missing — run: composer init (see wp-bootstrap skill references/composer-setup.md)');
+        }
+        if (!structure.js.hasBiome) {
+            actions.push('⚠  biome.json missing — run: npm install --save-dev @biomejs/biome && npx biome init');
+        }
+        if (!structure.playground.hasPlayground) {
+            actions.push('⚠  Playground not configured — run playground-start.sh to get started');
+        }
+        if (!structure.hasWpeRemote && !hasWpeConfig) {
+            actions.push('⚠  No WP Engine remotes — add --wpe-prod/--wpe-staging/--wpe-dev or configure manually');
+        }
+        return formatter.success({
+            structure,
+            detectOnly: false,
+            actions,
+            filesCreated,
+            dryRun,
+        });
+    }
+    catch (error) {
+        const err = error;
+        return formatter.fail({
+            code: 'BOOTSTRAP_FAILED',
+            message: err.message || 'Bootstrap failed',
+            exitCode: err.exitCode ?? ExitCode.ERROR,
+        });
+    }
+}