wordpress-agent-kit 0.2.1 → 0.3.0

package/dist/commands/run-playground.js

@@ -1,6 +1,8 @@
-import { Command } from 'commander';
-import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { Command } from 'commander';
+import { ExitCode } from '../utils/exit-codes.js';
+import { OutputFormatter, createFormatter } from '../utils/output.js';
 import { PACKAGE_ROOT } from '../utils/paths.js';
 /**
  * Command to run a local WordPress Playground instance.
@@ -8,21 +10,64 @@ import { PACKAGE_ROOT } from '../utils/paths.js';
  */
 export const runPlaygroundCommand = new Command('playground')
     .description('Run local WordPress Playground')
-    .action(() => {
-    const port = process.env.PORT || '9400';
+    .option('--port <port>', 'Port to run on', '9400')
+    .option('--no-auto-mount', 'Disable auto-mount of current directory')
+    .action(async (options, command) => {
+    const globalOpts = command.parent?.opts() || {};
+    const formatter = createFormatter(globalOpts, 'playground', '0.0.0');
+    const port = process.env.PORT || options.port;
     const blueprintPath = path.join(PACKAGE_ROOT, 'playground', 'blueprint.json');
+    if (!globalOpts.json && !globalOpts.quiet) {
+        console.log(`Starting WordPress Playground on port ${port}...`);
+        console.log(`Blueprint: ${blueprintPath}`);
+    }
     const args = [
         '@wp-playground/cli@latest',
         'server',
-        '--auto-mount',
+        options.autoMount ? '--auto-mount' : '',
         `--port=${port}`,
-        `--blueprint=${blueprintPath}`
-    ];
-    console.log(`Starting WordPress Playground on port ${port}...`);
-    const result = spawnSync('npx', args, {
-        cwd: PACKAGE_ROOT,
-        stdio: 'inherit',
-        shell: process.platform === 'win32'
-    });
-    process.exit(result.status || 0);
+        `--blueprint=${blueprintPath}`,
+    ].filter(Boolean);
+    if (globalOpts.dryRun) {
+        const dryRunResult = formatter.success({
+            wouldExecute: true,
+            actions: [
+                {
+                    type: 'create',
+                    target: `localhost:${port}`,
+                    description: 'Start WP Playground server with blueprint',
+                },
+            ],
+            summary: { port: Number(port), blueprint: blueprintPath },
+        });
+        process.exit(OutputFormatter.getExitCode(dryRunResult));
+    }
+    try {
+        const result = spawnSync('npx', args, {
+            cwd: PACKAGE_ROOT,
+            stdio: 'inherit',
+            shell: process.platform === 'win32',
+        });
+        if (result.status !== 0) {
+            const errorResult = formatter.fail({
+                code: 'PLAYGROUND_FAILED',
+                message: `Playground exited with code ${result.status}`,
+                exitCode: ExitCode.ERROR,
+            });
+            process.exit(OutputFormatter.getExitCode(errorResult));
+        }
+        if (globalOpts.json) {
+            const successResult = formatter.success({ port: Number(port), status: 'completed' });
+            process.exit(OutputFormatter.getExitCode(successResult));
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const errorResult = formatter.fail({
+            code: 'PLAYGROUND_ERROR',
+            message: errorMessage,
+            exitCode: ExitCode.ERROR,
+        });
+        process.exit(OutputFormatter.getExitCode(errorResult));
+    }
 });

package/dist/commands/setup.js

@@ -1,164 +1,217 @@
-import { Command } from 'commander';
-import * as p from '@clack/prompts';
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
+import * as p from '@clack/prompts';
+import { Command } from 'commander';
+import { configureAgentsMdApi, installKitApi, } from '../lib/api.js';
+import { PLATFORM_FOLDERS } from '../lib/installer.js';
+import { formatDetectionResults, hasConfidentDetection, mapProjectType, mapTechStack, } from '../lib/triage-mapper.js';
+import { ExitCode } from '../utils/exit-codes.js';
+import { OutputFormatter, createFormatter } from '../utils/output.js';
 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';
+const VALID_PROJECT_TYPES = ['plugin', 'theme', 'block-theme', 'site', 'blocks', 'other'];
+function isValidProjectType(type) {
+    return VALID_PROJECT_TYPES.includes(type);
+}
+function isDryRunResult(result) {
+    return result.success && 'wouldExecute' in (result.data || {});
+}
+function isRegularResult(result) {
+    return result.success && !('wouldExecute' in (result.data || {}));
+}
 /**
- * Command to interactively set up the WordPress Agent Kit.
- * Handles detection of project type, installation, and configuration of AGENTS.md.
+ * Interactive/Headless setup for WordPress Agent Kit.
+ * Supports both interactive prompts and --auto/--project-type/--tech-stack for headless use.
  */
 export const setupCommand = new Command('setup')
-    .description('Interactive setup for WordPress Agent Kit')
+    .description('Interactive or headless 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) => {
+    .option('--auto', 'Run triage, apply detected values, skip prompts', false)
+    .option('--project-type <type>', 'Project type: plugin, theme, block-theme, site, blocks, other')
+    .option('--tech-stack <list>', 'Comma-separated tech: gutenberg,interactivity,rest-api,wpcli,composer,phpstan,npm,playground')
+    .option('--package-manager <pm>', 'Package manager: npm, pnpm, yarn')
+    .option('-y, --yes', 'Accept all confirmations (requires --project-type in headless mode)')
+    .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, 'setup', '0.0.0');
+        const result = formatter.fail({
+            code: 'INVALID_PLATFORM',
+            message: `Invalid platform: ${platform}. Valid options: ${validPlatforms.join(', ')}`,
+            exitCode: ExitCode.INVALID_ARGS,
+        });
+        process.exit(OutputFormatter.getExitCode(result));
     }
-    const platformFolder = PLATFORM_FOLDERS[platform];
-    console.clear();
-    p.intro('WordPress Agent Kit Setup');
+    const formatter = createFormatter(globalOpts, 'setup', '0.0.0');
     const targetDir = path.resolve(dir);
-    // Check if target directory exists
+    const platformFolder = PLATFORM_FOLDERS[platform];
+    const isHeadless = options.auto || options.projectType || globalOpts.json || globalOpts.quiet;
+    // Create target directory if needed
     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 {
+        if (isHeadless) {
             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);
+        else {
+            const shouldCreate = await p.confirm({
+                message: `Target directory doesn't exist: ${targetDir}\nCreate it?`,
+                initialValue: true,
+            });
+            if (p.isCancel(shouldCreate) || !shouldCreate) {
+                const result = formatter.fail({
+                    code: 'CANCELLED',
+                    message: 'Setup cancelled.',
+                    exitCode: ExitCode.CANCELLED,
+                });
+                process.exit(OutputFormatter.getExitCode(result));
+            }
+            fs.mkdirSync(targetDir, { recursive: true });
         }
     }
-    p.log.info(`Setting up kit in: ${targetDir} (platform: ${platform})`);
-    // Check if kit is already installed
+    // Install kit if not present or --reset
     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);
+    const needsInstall = options.reset || !fs.existsSync(agentsPath);
+    if (needsInstall) {
+        if (!isHeadless) {
+            const shouldInstall = await p.confirm({
+                message: 'Kit not found in target repo. Install it first?',
+                initialValue: true,
+            });
+            if (p.isCancel(shouldInstall) || !shouldInstall) {
+                const result = formatter.fail({
+                    code: 'CANCELLED',
+                    message: 'Setup cancelled.',
+                    exitCode: ExitCode.CANCELLED,
+                });
+                process.exit(OutputFormatter.getExitCode(result));
+            }
         }
-    }
-    else if (!fs.existsSync(agentsPath)) {
-        const shouldInstall = await p.confirm({
-            message: 'Kit not found in target repo. Install it first?',
-            initialValue: true,
+        const installResult = await installKitApi({
+            targetDir,
+            platform,
+            force: options.reset,
+            dryRun: globalOpts.dryRun,
         });
-        if (p.isCancel(shouldInstall) || !shouldInstall) {
-            p.cancel('Setup cancelled.');
-            process.exit(0);
+        if (!installResult.success) {
+            process.exit(OutputFormatter.getExitCode(installResult));
         }
-        const s = p.spinner();
-        s.start('Installing kit files...');
-        try {
-            await installKit(targetDir, platform);
-            s.stop('Kit installed successfully.');
+        if (globalOpts.json || globalOpts.quiet) {
+            // Continue silently in headless mode
         }
-        catch (err) {
-            s.stop('Installation failed.');
-            console.error(err.message);
-            process.exit(1);
+        else {
+            console.log('✓ Kit installed');
         }
     }
-    // Run project triage BEFORE asking any questions
+    // Run project triage
     let triageResult = null;
     let detectedType = null;
     let detectedTech = [];
-    // Try to find triage script in multiple locations
+    let detectedPackageManager = 'npm/pnpm';
     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'),
+        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));
+    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,
+        const result = spawnSync('node', [triageScriptPath], {
+            cwd: targetDir,
+            encoding: 'utf-8',
         });
-        if (p.isCancel(confirmDetection)) {
-            p.cancel('Setup cancelled.');
-            process.exit(0);
+        if (result.status === 0 && result.stdout) {
+            triageResult = JSON.parse(result.stdout.trim());
+            detectedType = mapProjectType(triageResult.project?.primary ?? '');
+            detectedTech = mapTechStack(triageResult);
+            if (triageResult.tooling?.node?.packageManager) {
+                detectedPackageManager = triageResult.tooling.node.packageManager;
+            }
         }
-        useDetectedValues = confirmDetection;
     }
-    else if (triageResult) {
-        if (detectedType || detectedTech.length > 0) {
-            p.note(formatDetectionResults(detectedType, detectedTech, triageResult), 'Partial Detection (will be used as defaults)');
+    // Determine project config
+    let projectConfig;
+    if (options.auto && triageResult) {
+        // Auto mode: use detected values
+        if (!detectedType || detectedType === 'other') {
+            const result = formatter.fail({
+                code: 'AUTO_DETECTION_FAILED',
+                message: 'Auto-detection could not determine project type confidently. Use --project-type explicitly.',
+                exitCode: ExitCode.VALIDATION_ERROR,
+            });
+            process.exit(OutputFormatter.getExitCode(result));
         }
-    }
-    let projectInfo;
-    if (useDetectedValues) {
-        projectInfo = {
+        projectConfig = {
             projectType: detectedType,
             techStack: detectedTech,
+            packageManager: detectedPackageManager,
         };
-        p.log.success('Using auto-detected configuration.');
+        if (!globalOpts.json && !globalOpts.quiet) {
+            console.log(`Auto-detected: ${detectedType} (${detectedTech.join(', ')})`);
+        }
+    }
+    else if (options.projectType) {
+        // Explicit project type provided (headless)
+        if (!isValidProjectType(options.projectType)) {
+            const result = formatter.fail({
+                code: 'INVALID_PROJECT_TYPE',
+                message: `Invalid project type: ${options.projectType}. Valid: ${VALID_PROJECT_TYPES.join(', ')}`,
+                exitCode: ExitCode.INVALID_ARGS,
+            });
+            process.exit(OutputFormatter.getExitCode(result));
+        }
+        projectConfig = {
+            projectType: options.projectType,
+            techStack: options.techStack
+                ? options.techStack.split(',').map((s) => s.trim())
+                : detectedTech,
+            packageManager: options.packageManager || detectedPackageManager,
+        };
+    }
+    else if (isHeadless) {
+        // Headless without enough info
+        const result = formatter.fail({
+            code: 'MISSING_CONFIG',
+            message: 'Headless mode requires --project-type (and optionally --tech-stack). Use --auto for auto-detection.',
+            exitCode: ExitCode.INVALID_ARGS,
+        });
+        process.exit(OutputFormatter.getExitCode(result));
     }
     else {
-        projectInfo = await p.group({
-            projectType: () => p.select({
+        // Interactive mode - prompt user
+        if (!globalOpts.json && !globalOpts.quiet) {
+            console.clear();
+            p.intro('WordPress Agent Kit Setup');
+            console.log(`Setting up kit in: ${targetDir} (platform: ${platform})`);
+        }
+        let useDetected = false;
+        if (triageResult && hasConfidentDetection(detectedType)) {
+            if (!globalOpts.json && !globalOpts.quiet) {
+                p.note(formatDetectionResults(detectedType, detectedTech), 'Auto-Detection Results');
+                const confirm = await p.confirm({
+                    message: 'Use these detected values?',
+                    initialValue: true,
+                });
+                if (p.isCancel(confirm))
+                    process.exit(ExitCode.CANCELLED);
+                useDetected = confirm;
+            }
+        }
+        else if (triageResult && (detectedType || detectedTech.length > 0)) {
+            if (!globalOpts.json && !globalOpts.quiet) {
+                p.note(formatDetectionResults(detectedType, detectedTech), 'Partial Detection (used as defaults)');
+            }
+        }
+        if (useDetected) {
+            projectConfig = {
+                projectType: detectedType,
+                techStack: detectedTech,
+                packageManager: detectedPackageManager,
+            };
+        }
+        else {
+            // Interactive prompts
+            const projectTypePrompt = p.select({
                 message: 'What type of WordPress project is this?',
                 options: [
                     { value: 'plugin', label: 'Plugin' },
@@ -170,11 +223,15 @@ export const setupCommand = new Command('setup')
                     { value: 'unsure', label: "I'm not sure" },
                 ],
                 initialValue: detectedType || undefined,
-            }),
-            techStack: () => p.multiselect({
+            });
+            const techStackPrompt = p.multiselect({
                 message: 'Select technologies (or skip if unsure):',
                 options: [
-                    { value: 'gutenberg', label: 'Gutenberg Blocks', hint: 'block.json, @wordpress/blocks' },
+                    {
+                        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' },
@@ -185,53 +242,55 @@ export const setupCommand = new Command('setup')
                 ],
                 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 { projectType, techStack } = await p.group({ projectType: () => projectTypePrompt, techStack: () => techStackPrompt }, { onCancel: () => process.exit(ExitCode.CANCELLED) });
+            projectConfig = {
+                projectType: (projectType === 'unsure' ? 'other' : projectType),
+                techStack,
+                packageManager: detectedPackageManager,
+            };
         }
     }
-    const customizeAgents = await p.confirm({
-        message: 'Customize AGENTS.md with project details?',
-        initialValue: true,
+    // Configure AGENTS.md
+    const configureResult = await configureAgentsMdApi({
+        targetDir,
+        platform,
+        config: projectConfig,
+        dryRun: globalOpts.dryRun,
     });
-    if (p.isCancel(customizeAgents)) {
-        p.cancel('Setup cancelled.');
-        process.exit(0);
+    if (!configureResult.success) {
+        process.exit(OutputFormatter.getExitCode(configureResult));
     }
-    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');
+    // Success output
+    if (globalOpts.json || globalOpts.quiet) {
+        let modified = [];
+        let skipped = [];
+        if (isRegularResult(configureResult)) {
+            modified = configureResult.data.modified;
+            skipped = configureResult.data.skipped;
         }
-        catch (err) {
-            p.log.warn(`Could not update AGENTS.md: ${err.message}`);
+        else if (isDryRunResult(configureResult)) {
+            // Dry-run
+            modified = configureResult.data.summary.modified;
+            skipped = configureResult.data.summary.skipped;
         }
-    }
-    // Workflow instructions
-    if (fs.existsSync(platformInstructionsPath)) {
-        const customizeWorkflow = await p.confirm({
-            message: 'Open workflow instructions for manual editing?',
-            initialValue: false,
+        const result = formatter.success({
+            targetDir,
+            platform,
+            config: projectConfig,
+            modified,
+            skipped,
         });
-        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');
-        }
+        process.exit(OutputFormatter.getExitCode(result));
     }
-    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!');
+    // Human output
+    console.log('✓ Setup complete');
+    console.log(`  Project: ${projectConfig.projectType}`);
+    console.log(`  Tech stack: ${projectConfig.techStack.join(', ') || 'none'}`);
+    console.log(`  Package manager: ${projectConfig.packageManager}`);
+    console.log('\nNext steps:');
+    console.log(`  1. Review ${path.join(targetDir, 'AGENTS.md')}`);
+    console.log(`  2. Customize ${path.join(targetDir, platformFolder, 'prompts/')}`);
+    console.log(`  3. Run triage: node ${path.join(targetDir, platformFolder, 'skills/wp-project-triage/scripts/detect_wp_project.mjs')}`);
+    process.exit(0);
 });

package/dist/commands/sync-skills.js

@@ -1,70 +1,43 @@
 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';
+import { syncSkillsApi } from '../lib/api.js';
+import { OutputFormatter } 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 sync skills from the official WordPress agent-skills repository.
- * Can checkout a specific branch or tag.
+ * Supports --json, --ndjson, --dry-run flags.
  */
 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);
+    .description('Sync skills from the official WordPress/agent-skills repository')
+    .argument('[ref]', 'Branch or tag to checkout', 'trunk')
+    .option('--ref <ref>', 'Branch or tag to checkout (alias for argument)')
+    .action(async (refArg, options, command) => {
+    const globalOpts = command.parent?.opts() || {};
+    const ref = options.ref || refArg;
+    const result = await syncSkillsApi({
+        targetDir: process.cwd(),
+        ref,
+        dryRun: globalOpts.dryRun,
+    });
+    if (globalOpts.json || globalOpts.ndjson || globalOpts.quiet) {
+        process.exit(OutputFormatter.getExitCode(result));
     }
-    // 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);
+    if (isRegularResult(result)) {
+        const data = result.data;
+        console.log(`✓ Synced ${data.skillsSynced} skills from WordPress/agent-skills@${ref}`);
+        console.log(`  Method: ${data.method}`);
+        console.log(`  Duration: ${data.durationMs}ms`);
     }
-    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;
+    else if (isDryRunResult(result)) {
+        // Dry-run result
+        console.log(`✓ Dry-run: ${result.data.summary.skillsSynced} skills would be synced`);
     }
-    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 });
+    else {
+        console.error(`✗ Sync failed: ${result.error?.message}`);
     }
-    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');
+    process.exit(result.success ? 0 : 1);
 });