wordpress-agent-kit 0.2.1 → 0.2.2

package/dist/lib/api.js

@@ -0,0 +1,456 @@
+/**
+ * Programmatic API for WordPress Agent Kit.
+ * Can be imported directly by agents/scripts: `import { installKit } from 'wordpress-agent-kit/api'`
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { ExitCode, withExitCode } from '../utils/exit-codes.js';
+import { OutputFormatter } from '../utils/output.js';
+import { PACKAGE_ROOT } from '../utils/paths.js';
+import { installKit } from './installer.js';
+/**
+ * Install the WordPress Agent Kit programmatically.
+ */
+export async function installKitApi(options) {
+    const startTime = Date.now();
+    const formatter = new OutputFormatter('json', 'install', '0.0.0');
+    try {
+        const { targetDir, platform, force = false, dryRun = false } = options;
+        if (dryRun) {
+            return dryRunInstall(targetDir, platform, force);
+        }
+        await withExitCode(async () => {
+            await installKit(targetDir, platform);
+            return { success: true };
+        });
+        const filesCreated = getInstalledFiles(targetDir, platform);
+        const durationMs = Date.now() - startTime;
+        return formatter.success({
+            targetDir,
+            platform,
+            filesCreated,
+            filesSkipped: [],
+            errors: [],
+            durationMs,
+        });
+    }
+    catch (error) {
+        const err = error;
+        return formatter.fail({
+            code: err.code || 'INSTALL_FAILED',
+            message: err.message || 'Installation failed',
+            exitCode: err.exitCode ?? ExitCode.ERROR,
+            details: { platform: options.platform, targetDir: options.targetDir },
+        });
+    }
+}
+/**
+ * Dry-run preview for install.
+ */
+function dryRunInstall(targetDir, platform, force) {
+    const platformFolder = getPlatformFolder(platform);
+    const actions = [];
+    const sourceGithub = path.join(PACKAGE_ROOT, '.github');
+    const targetPlatform = path.join(targetDir, platformFolder);
+    const templatePath = path.join(PACKAGE_ROOT, 'AGENTS.template.md');
+    const targetAgentsTemplate = path.join(targetDir, 'AGENTS.template.md');
+    const targetAgents = path.join(targetDir, 'AGENTS.md');
+    // Platform folder
+    if (fs.existsSync(sourceGithub)) {
+        if (fs.existsSync(targetPlatform) && !force) {
+            actions.push({
+                type: 'update',
+                target: targetPlatform,
+                description: `Would update ${platformFolder} (use --force to overwrite)`,
+            });
+        }
+        else {
+            actions.push({
+                type: 'copy',
+                source: sourceGithub,
+                target: targetPlatform,
+                description: `Copy ${platformFolder} from kit`,
+            });
+        }
+    }
+    // AGENTS.template.md
+    if (fs.existsSync(templatePath)) {
+        actions.push({
+            type: 'copy',
+            source: templatePath,
+            target: targetAgentsTemplate,
+            description: 'Copy AGENTS.template.md',
+        });
+    }
+    // AGENTS.md
+    if (!fs.existsSync(targetAgents) || force) {
+        if (fs.existsSync(templatePath)) {
+            actions.push({
+                type: 'copy',
+                source: templatePath,
+                target: targetAgents,
+                description: 'Create AGENTS.md from template',
+            });
+        }
+    }
+    else {
+        actions.push({
+            type: 'update',
+            target: targetAgents,
+            description: 'AGENTS.md exists (use --force to overwrite)',
+        });
+    }
+    return new OutputFormatter('json', 'install', '0.0.0').success({
+        wouldExecute: true,
+        actions,
+        summary: {
+            targetDir,
+            platform,
+            filesCreated: actions.filter((a) => a.type === 'copy').map((a) => a.target),
+            filesSkipped: actions.filter((a) => a.type === 'update').map((a) => a.target),
+            errors: [],
+            durationMs: 0,
+        },
+    });
+}
+/**
+ * Sync skills from WordPress/agent-skills programmatically.
+ */
+export async function syncSkillsApi(options = {}) {
+    const startTime = Date.now();
+    const formatter = new OutputFormatter('json', 'sync-skills', '0.0.0');
+    const targetDir = options.targetDir || process.cwd();
+    const ref = options.ref || 'trunk';
+    if (options.dryRun) {
+        return dryRunSyncSkills(targetDir, ref);
+    }
+    try {
+        const result = await withExitCode(async () => {
+            const repoRoot = targetDir;
+            const submodulePath = path.join('vendor', 'wp-agent-skills');
+            const vendorSkillsDir = path.join(repoRoot, submodulePath);
+            const submoduleGitDir = path.join(vendorSkillsDir, '.git');
+            // Clone or update
+            if (!fs.existsSync(submoduleGitDir)) {
+                fs.mkdirSync(path.join(repoRoot, 'vendor'), { recursive: true });
+                const cloneResult = spawnSync('git', ['clone', 'https://github.com/WordPress/agent-skills.git', submodulePath], {
+                    cwd: repoRoot,
+                    encoding: 'utf-8',
+                });
+                if (cloneResult.status !== 0) {
+                    throw new Error(`Git clone failed: ${cloneResult.stderr?.toString()}`);
+                }
+            }
+            else {
+                const fetchResult = spawnSync('git', ['fetch', '--all', '--tags'], {
+                    cwd: vendorSkillsDir,
+                    encoding: 'utf-8',
+                });
+                if (fetchResult.status !== 0) {
+                    throw new Error(`Git fetch failed: ${fetchResult.stderr?.toString()}`);
+                }
+            }
+            // Checkout ref
+            const checkoutResult = spawnSync('git', ['checkout', ref], {
+                cwd: vendorSkillsDir,
+                encoding: 'utf-8',
+            });
+            if (checkoutResult.status !== 0) {
+                throw new Error(`Git checkout failed: ${checkoutResult.stderr?.toString()}`);
+            }
+            const pullResult = spawnSync('git', ['pull', 'origin', ref], {
+                cwd: vendorSkillsDir,
+                encoding: 'utf-8',
+            });
+            if (pullResult.status !== 0) {
+                throw new Error(`Git pull failed: ${pullResult.stderr?.toString()}`);
+            }
+            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');
+            let method = 'direct-copy';
+            let skillsSynced = 0;
+            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 });
+                const buildResult = spawnSync('node', ['shared/scripts/skillpack-build.mjs', '--clean', '--targets=vscode'], {
+                    cwd: vendorSkillsDir,
+                    encoding: 'utf-8',
+                });
+                if (buildResult.status !== 0) {
+                    throw new Error(`Skillpack build failed: ${buildResult.stderr?.toString()}`);
+                }
+                const installResult = spawnSync('node', [
+                    'shared/scripts/skillpack-install.mjs',
+                    `--dest=${repoRoot}`,
+                    '--targets=vscode',
+                    '--from=dist',
+                    '--mode=replace',
+                ], { cwd: vendorSkillsDir, encoding: 'utf-8' });
+                if (installResult.status !== 0) {
+                    throw new Error(`Skillpack install failed: ${installResult.stderr?.toString()}`);
+                }
+                method = 'skillpack';
+                if (fs.existsSync(targetSkills)) {
+                    skillsSynced = fs.readdirSync(targetSkills).length;
+                }
+            }
+            else {
+                const sourceSkills = path.join(vendorSkillsDir, '.github', 'skills');
+                if (!fs.existsSync(sourceSkills)) {
+                    throw new Error(`Upstream skills not found at ${sourceSkills}`);
+                }
+                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 });
+                skillsSynced = fs.readdirSync(targetSkills).length;
+            }
+            return { success: true, skillsSynced, method };
+        });
+        return formatter.success({
+            targetDir,
+            skillsSynced: result.skillsSynced,
+            sourceUrl: 'https://github.com/WordPress/agent-skills.git',
+            ref,
+            durationMs: Date.now() - startTime,
+            method: result.method,
+        });
+    }
+    catch (error) {
+        const err = error;
+        return formatter.fail({
+            code: err.code || 'SYNC_FAILED',
+            message: err.message || 'Sync failed',
+            exitCode: err.exitCode ?? ExitCode.ERROR,
+            details: { ref, targetDir },
+        });
+    }
+}
+/**
+ * Dry-run preview for sync-skills.
+ */
+function dryRunSyncSkills(targetDir, ref) {
+    const actions = [];
+    const targetSkills = path.join(targetDir, '.github', 'skills');
+    const vendorDir = path.join(targetDir, 'vendor', 'wp-agent-skills');
+    actions.push({
+        type: 'mkdir',
+        target: path.join(targetDir, 'vendor'),
+        description: 'Create vendor directory',
+    });
+    if (!fs.existsSync(vendorDir)) {
+        actions.push({
+            type: 'create',
+            target: vendorDir,
+            description: 'Clone WordPress/agent-skills repository',
+        });
+    }
+    else {
+        actions.push({
+            type: 'update',
+            target: vendorDir,
+            description: `Fetch and checkout ${ref}`,
+        });
+    }
+    if (fs.existsSync(targetSkills)) {
+        actions.push({
+            type: 'delete',
+            target: targetSkills,
+            description: 'Remove existing skills directory',
+        });
+    }
+    actions.push({
+        type: 'create',
+        target: targetSkills,
+        description: 'Install synced skills',
+    });
+    return new OutputFormatter('json', 'sync-skills', '0.0.0').success({
+        wouldExecute: true,
+        actions,
+        summary: {
+            targetDir,
+            skillsSynced: 0,
+            sourceUrl: 'https://github.com/WordPress/agent-skills.git',
+            ref,
+            durationMs: 0,
+            method: 'skillpack',
+        },
+    });
+}
+/**
+ * Run project triage detection programmatically.
+ */
+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'),
+            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));
+        if (!triageScriptPath) {
+            return formatter.fail({
+                code: 'TRIAGE_NOT_FOUND',
+                message: 'Project triage script not found. Run sync-skills first.',
+                exitCode: ExitCode.NOT_FOUND,
+            });
+        }
+        const result = spawnSync('node', [triageScriptPath], {
+            cwd: targetDir,
+            encoding: 'utf-8',
+        });
+        if (result.status !== 0) {
+            return formatter.fail({
+                code: 'TRIAGE_FAILED',
+                message: result.stderr?.toString() || 'Triage script failed',
+                exitCode: ExitCode.ERROR,
+            });
+        }
+        const triageResult = JSON.parse(result.stdout.trim());
+        return formatter.success(triageResult);
+    }
+    catch (error) {
+        const err = error;
+        return formatter.fail({
+            code: 'TRIAGE_ERROR',
+            message: err.message || 'Triage failed',
+            exitCode: ExitCode.ERROR,
+        });
+    }
+}
+/**
+ * Configure AGENTS.md with project details programmatically.
+ */
+export async function configureAgentsMdApi(options) {
+    const formatter = new OutputFormatter('json', 'configure', '0.0.0');
+    const { targetDir, platform, config, dryRun = false } = options;
+    try {
+        const platformFolder = getPlatformFolder(platform);
+        const agentsPath = path.join(targetDir, 'AGENTS.md');
+        const platformInstructionsPath = path.join(targetDir, platformFolder, 'instructions', 'wordpress-workflow.instructions.md');
+        if (dryRun) {
+            const actions = [];
+            if (fs.existsSync(agentsPath)) {
+                actions.push({
+                    type: 'update',
+                    target: agentsPath,
+                    description: `Update AGENTS.md with project type: ${config.projectType}, tech: ${config.techStack.join(', ')}`,
+                });
+            }
+            else {
+                actions.push({
+                    type: 'create',
+                    target: agentsPath,
+                    description: 'Create AGENTS.md with project configuration',
+                });
+            }
+            if (fs.existsSync(platformInstructionsPath)) {
+                actions.push({
+                    type: 'update',
+                    target: platformInstructionsPath,
+                    description: 'Workflow instructions available for customization',
+                });
+            }
+            return formatter.success({
+                wouldExecute: true,
+                actions,
+                summary: {
+                    targetDir,
+                    modified: [agentsPath],
+                    skipped: [],
+                    dryRun: true,
+                },
+            });
+        }
+        const modified = [];
+        const skipped = [];
+        // Update AGENTS.md
+        if (fs.existsSync(agentsPath)) {
+            let agentsContent = fs.readFileSync(agentsPath, 'utf-8');
+            const pm = config.packageManager || 'npm/pnpm';
+            agentsContent = agentsContent.replace(/\*\*Tooling\*\*: .*/, `**Tooling**: ${config.techStack.includes('composer') ? 'Composer for PHP' : ''}${config.techStack.includes('npm') ? `, ${pm} for JS` : ''}.`);
+            fs.writeFileSync(agentsPath, agentsContent, 'utf-8');
+            modified.push(agentsPath);
+        }
+        else {
+            skipped.push(agentsPath);
+        }
+        // Note workflow instructions
+        if (fs.existsSync(platformInstructionsPath)) {
+            modified.push(platformInstructionsPath);
+        }
+        else {
+            skipped.push(platformInstructionsPath);
+        }
+        return formatter.success({
+            targetDir,
+            modified,
+            skipped,
+            dryRun: false,
+        });
+    }
+    catch (error) {
+        const err = error;
+        return formatter.fail({
+            code: 'CONFIGURE_FAILED',
+            message: err.message || 'Configuration failed',
+            exitCode: ExitCode.ERROR,
+        });
+    }
+}
+/**
+ * Get platform folder name.
+ */
+function getPlatformFolder(platform) {
+    const folders = {
+        github: '.github',
+        cursor: '.cursor',
+        claude: '.claude',
+        agent: '.agent',
+        pi: '.pi/agent',
+    };
+    return folders[platform];
+}
+/**
+ * Get list of files that would be/are installed.
+ */
+function getInstalledFiles(targetDir, platform) {
+    const platformFolder = getPlatformFolder(platform);
+    const files = [];
+    const targetPlatform = path.join(targetDir, platformFolder);
+    if (fs.existsSync(targetPlatform)) {
+        function walk(dir, prefix = '') {
+            const entries = fs.readdirSync(dir);
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry);
+                const relPath = path.join(prefix, entry);
+                const stat = fs.statSync(fullPath);
+                if (stat.isDirectory()) {
+                    walk(fullPath, relPath);
+                }
+                else {
+                    files.push(path.join(platformFolder, relPath));
+                }
+            }
+        }
+        walk(targetPlatform);
+    }
+    const agentsPath = path.join(targetDir, 'AGENTS.md');
+    if (fs.existsSync(agentsPath)) {
+        files.push('AGENTS.md');
+    }
+    const agentsTemplatePath = path.join(targetDir, 'AGENTS.template.md');
+    if (fs.existsSync(agentsTemplatePath)) {
+        files.push('AGENTS.template.md');
+    }
+    return files;
+}
+export { ExitCode } from '../utils/exit-codes.js';
+export { OutputFormatter, createFormatter, parseOutputFormat } from '../utils/output.js';

package/dist/lib/triage-mapper.js

@@ -15,14 +15,14 @@ export function mapProjectType(primary) {
         'wp-theme': 'theme',
         'wp-site': 'site',
         'wp-core': 'other',
-        'gutenberg': 'blocks',
-        'unknown': null,
+        gutenberg: 'blocks',
+        unknown: null,
     };
     return typeMap[primary] || null;
 }
 /**
  * Maps triage signals and tooling to tech stack array
- * @param {object} triageResult - Full triage result object
+ * @param {TriageResult} triageResult - Full triage result object
  * @returns {string[]} - Array of tech stack values
  */
 export function mapTechStack(triageResult) {
@@ -60,39 +60,37 @@ export function mapTechStack(triageResult) {
 /**
  * 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) {
+export function hasConfidentDetection(detectedType) {
     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) {
+export function formatDetectionResults(detectedType, detectedTech) {
     const typeLabels = {
-        'plugin': 'WordPress Plugin',
-        'theme': 'WordPress Theme',
+        plugin: 'WordPress Plugin',
+        theme: 'WordPress Theme',
         'block-theme': 'Block Theme',
-        'site': 'Full Site / Multisite',
-        'blocks': 'Gutenberg Blocks',
-        'other': 'Other / Mixed',
+        site: 'Full Site / Multisite',
+        blocks: 'Gutenberg Blocks',
+        other: 'Other / Mixed',
     };
     const techLabels = {
-        'gutenberg': 'Blocks',
-        'interactivity': 'Interactivity API',
-        'wpcli': 'WP-CLI',
+        gutenberg: 'Blocks',
+        interactivity: 'Interactivity API',
+        wpcli: 'WP-CLI',
         'rest-api': 'REST API',
-        'composer': 'Composer',
-        'phpstan': 'PHPStan',
-        'npm': 'npm/package.json',
-        'playground': 'Playground',
+        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(', ');
+    const techList = detectedTech.map((t) => techLabels[t] || t).join(', ');
     return `Project Type: ${typeLabel}\nTech Stack: ${techList}`;
 }

package/dist/utils/exit-codes.js

@@ -0,0 +1,60 @@
+/**
+ * Semantic exit codes for the CLI.
+ * Allows scripts and agents to programmatically determine failure reasons.
+ */
+export const ExitCode = {
+    /** Success */
+    OK: 0,
+    /** General/unknown error */
+    ERROR: 1,
+    /** Invalid command-line arguments or usage */
+    INVALID_ARGS: 2,
+    /** Target not found (ENOENT) */
+    NOT_FOUND: 3,
+    /** Permission denied (EACCES) */
+    PERMISSION_DENIED: 4,
+    /** File/directory already exists (EEXIST) - use --force to override */
+    ALREADY_EXISTS: 5,
+    /** Git/submodule operation failed */
+    GIT_ERROR: 6,
+    /** Network/fetch operation failed */
+    NETWORK_ERROR: 7,
+    /** Validation failed (schema, input, config) */
+    VALIDATION_ERROR: 8,
+    /** Cancelled by user (SIGINT) */
+    CANCELLED: 130,
+};
+/**
+ * Maps Node.js errno to semantic exit code.
+ */
+export function mapErrnoToExitCode(errno) {
+    switch (errno) {
+        case 'ENOENT':
+            return ExitCode.NOT_FOUND;
+        case 'EACCES':
+        case 'EPERM':
+            return ExitCode.PERMISSION_DENIED;
+        case 'EEXIST':
+            return ExitCode.ALREADY_EXISTS;
+        default:
+            return ExitCode.ERROR;
+    }
+}
+/**
+ * Wraps an async operation and maps errors to exit codes.
+ * Re-throws with exitCode property attached.
+ */
+export async function withExitCode(operation, onError) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        const err = error;
+        const exitCode = err.exitCode ?? mapErrnoToExitCode(err.code);
+        const enhancedError = Object.assign(err, { exitCode });
+        if (onError) {
+            onError(enhancedError);
+        }
+        throw enhancedError;
+    }
+}

package/dist/utils/output.js

@@ -0,0 +1,96 @@
+import { ExitCode } from './exit-codes.js';
+/** Output formatter handles all CLI output modes */
+export class OutputFormatter {
+    format;
+    startTime;
+    commandName;
+    version;
+    ndjsonStarted = false;
+    constructor(format, commandName, version) {
+        this.format = format;
+        this.startTime = Date.now();
+        this.commandName = commandName;
+        this.version = version;
+    }
+    /** Set output format at runtime */
+    setFormat(format) {
+        this.format = format;
+    }
+    /** Build standard result envelope */
+    buildResult(success, data, error) {
+        return {
+            success,
+            data,
+            error,
+            meta: {
+                durationMs: Date.now() - this.startTime,
+                timestamp: new Date().toISOString(),
+                version: this.version,
+                command: this.commandName,
+            },
+        };
+    }
+    /** Output success result */
+    success(data) {
+        const result = this.buildResult(true, data);
+        this.emit(result);
+        return result;
+    }
+    /** Output error result */
+    fail(error) {
+        const result = this.buildResult(false, undefined, error);
+        this.emit(result);
+        return result;
+    }
+    /** Emit NDJSON progress event */
+    progress(event) {
+        if (this.format !== 'ndjson')
+            return;
+        const fullEvent = {
+            ...event,
+            timestamp: new Date().toISOString(),
+        };
+        console.log(JSON.stringify(fullEvent));
+    }
+    /** Start NDJSON stream */
+    startStream() {
+        if (this.format === 'ndjson') {
+            this.ndjsonStarted = true;
+        }
+    }
+    /** Emit raw object (used for JSON mode) */
+    emit(obj) {
+        switch (this.format) {
+            case 'json':
+            case 'ndjson':
+                console.log(JSON.stringify(obj));
+                break;
+            case 'human':
+                // Human mode: commands should handle their own console output
+                // This is a no-op for structured results
+                break;
+            case 'quiet':
+                // Suppress all output
+                break;
+        }
+    }
+    /** Get exit code from result */
+    static getExitCode(result) {
+        return result.success ? ExitCode.OK : (result.error?.exitCode ?? ExitCode.ERROR);
+    }
+}
+/** Parse output format from CLI flags */
+export function parseOutputFormat(json, quiet, ndjson) {
+    if (json)
+        return 'json';
+    if (ndjson)
+        return 'ndjson';
+    if (quiet)
+        return 'quiet';
+    return 'human';
+}
+/** Create formatter from parsed options */
+export function createFormatter(options, commandName, version) {
+    const format = parseOutputFormat(options.json, options.quiet, options.ndjson);
+    return new OutputFormatter(format, commandName, version);
+}

package/dist/utils/paths.js

@@ -1,5 +1,5 @@
-import { fileURLToPath } from 'node:url';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 // 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 ../