wordpress-agent-kit 0.2.1 → 0.3.0

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/lib/updater.js

@@ -0,0 +1,260 @@
+/**
+ * Safe update logic for WordPress Agent Kit installations.
+ * Tracks file origins and detects user modifications to avoid overwriting custom work.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { PACKAGE_ROOT } from '../utils/paths.js';
+import { PLATFORM_FOLDERS } from './installer.js';
+/** Get the platform folder for a target */
+export function getPlatformTarget(targetDir, platform) {
+    const folder = PLATFORM_FOLDERS[platform];
+    return path.join(targetDir, folder);
+}
+/** Get the manifest file path */
+function getManifestPath(targetDir, platform) {
+    return path.join(targetDir, `.wp-agent-kit-manifest.${platform}.json`);
+}
+/** Hash a file's content */
+function hashFile(filePath) {
+    const content = fs.readFileSync(filePath);
+    return crypto.createHash('sha256').update(content).digest('hex');
+}
+/** Walk a directory recursively, returning relative paths */
+function walkDir(dir) {
+    const result = [];
+    if (!fs.existsSync(dir))
+        return result;
+    const entries = fs.readdirSync(dir);
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry);
+        const stat = fs.statSync(fullPath);
+        if (stat.isDirectory()) {
+            const subPaths = walkDir(fullPath);
+            for (const sub of subPaths) {
+                result.push(path.join(entry, sub));
+            }
+        }
+        else {
+            result.push(entry);
+        }
+    }
+    return result;
+}
+/** Load existing manifest if present */
+export function loadManifest(targetDir, platform) {
+    const manifestPath = getManifestPath(targetDir, platform);
+    if (!fs.existsSync(manifestPath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Save manifest */
+function saveManifest(targetDir, platform, manifest) {
+    const manifestPath = getManifestPath(targetDir, platform);
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf-8');
+}
+/** Create a backup of target files before overwriting */
+function createBackup(targetDir, platform, files) {
+    if (files.length === 0)
+        return null;
+    const platformFolder = PLATFORM_FOLDERS[platform];
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupDir = path.join(targetDir, `.wp-agent-kit-backup-${timestamp}`);
+    for (const file of files) {
+        const srcPath = path.join(targetDir, platformFolder, file);
+        const destPath = path.join(backupDir, platformFolder, file);
+        if (fs.existsSync(srcPath)) {
+            fs.mkdirSync(path.dirname(destPath), { recursive: true });
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+    return backupDir;
+}
+/**
+ * Compute file changes between current state and what would be installed.
+ */
+export function computeChanges(targetDir, platform, force) {
+    const existingManifest = loadManifest(targetDir, platform);
+    const sourceDir = path.join(PACKAGE_ROOT, '.github');
+    const targetPlatform = getPlatformTarget(targetDir, platform);
+    const changes = [];
+    const sourceFiles = walkDir(sourceDir);
+    const targetFiles = fs.existsSync(targetPlatform) ? walkDir(targetPlatform) : [];
+    // Build lookup of known files from manifest
+    const knownFiles = new Map();
+    if (existingManifest) {
+        for (const entry of existingManifest.files) {
+            knownFiles.set(entry.path, entry.hash);
+        }
+    }
+    // Process source files
+    for (const sourceFile of sourceFiles) {
+        const targetPath = path.join(targetPlatform, sourceFile);
+        const sourceHash = hashFile(path.join(sourceDir, sourceFile));
+        if (!fs.existsSync(targetPath)) {
+            changes.push({
+                relativePath: sourceFile,
+                action: 'created',
+                reason: 'New file from kit',
+            });
+            continue;
+        }
+        const targetHash = hashFile(targetPath);
+        if (sourceHash === targetHash) {
+            // Identical - no change needed
+            changes.push({
+                relativePath: sourceFile,
+                action: 'unchanged',
+                reason: 'Content identical',
+            });
+        }
+        else if (knownFiles.has(sourceFile)) {
+            const manifestHash = knownFiles.get(sourceFile);
+            if (targetHash === manifestHash) {
+                // Same as original from manifest, safe to update
+                changes.push({
+                    relativePath: sourceFile,
+                    action: 'updated',
+                    reason: 'Safe update (no user modification)',
+                });
+            }
+            else if (force) {
+                changes.push({
+                    relativePath: sourceFile,
+                    action: 'updated',
+                    reason: 'Force update (overwriting user modification)',
+                });
+            }
+            else {
+                changes.push({
+                    relativePath: sourceFile,
+                    action: 'conflict',
+                    reason: 'User modified; skipped. Use --force to overwrite.',
+                });
+            }
+        }
+        else {
+            // Not in manifest (pre-manifest install or manual add), but exists
+            if (force) {
+                changes.push({
+                    relativePath: sourceFile,
+                    action: 'updated',
+                    reason: 'Force update (file not tracked in manifest)',
+                });
+            }
+            else {
+                changes.push({
+                    relativePath: sourceFile,
+                    action: 'skipped',
+                    reason: 'File exists but not tracked; skipped. Use --force to overwrite.',
+                });
+            }
+        }
+    }
+    // Note user-added files not in source (these are kept, not reported as changes)
+    const sourceSet = new Set(sourceFiles);
+    for (const targetFile of targetFiles) {
+        if (!sourceSet.has(targetFile)) {
+            changes.push({
+                relativePath: targetFile,
+                action: 'unchanged',
+                reason: 'User-added file (preserved)',
+            });
+        }
+    }
+    return changes;
+}
+/**
+ * Perform a safe update of the WordPress Agent Kit in the target directory.
+ * Compares files against manifest and source to avoid overwriting user modifications.
+ */
+export function updateKit(options) {
+    const { targetDir, platform, force = false, backup = true } = options;
+    const changes = computeChanges(targetDir, platform, force);
+    const sourceDir = path.join(PACKAGE_ROOT, '.github');
+    const targetPlatform = getPlatformTarget(targetDir, platform);
+    const created = [];
+    const updated = [];
+    const skipped = [];
+    const conflicts = [];
+    // Determine which files will be overwritten (for backup)
+    const filesToBackup = changes.filter((c) => c.action === 'updated').map((c) => c.relativePath);
+    let backupDir = null;
+    if (backup && filesToBackup.length > 0) {
+        backupDir = createBackup(targetDir, platform, filesToBackup);
+    }
+    // Apply changes
+    for (const change of changes) {
+        const sourcePath = path.join(sourceDir, change.relativePath);
+        const targetPath = path.join(targetPlatform, change.relativePath);
+        switch (change.action) {
+            case 'created':
+                fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+                fs.copyFileSync(sourcePath, targetPath);
+                created.push(change.relativePath);
+                break;
+            case 'updated':
+                fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+                fs.copyFileSync(sourcePath, targetPath);
+                updated.push(change.relativePath);
+                break;
+            case 'skipped':
+                skipped.push(change.relativePath);
+                break;
+            case 'conflict':
+                conflicts.push(change.relativePath);
+                break;
+            // 'unchanged' - do nothing
+        }
+    }
+    // Build and save new manifest
+    const newManifest = {
+        version: getPackageVersion(),
+        platform,
+        installedAt: new Date().toISOString(),
+        files: walkDir(sourceDir).map((file) => ({
+            path: file,
+            hash: hashFile(path.join(sourceDir, file)),
+        })),
+    };
+    saveManifest(targetDir, platform, newManifest);
+    return {
+        targetDir,
+        platform,
+        changes,
+        created,
+        updated,
+        skipped,
+        conflicts,
+        backupDir,
+        manifestUpdated: true,
+    };
+}
+/** Get current package version */
+function getPackageVersion() {
+    try {
+        const pkgPath = path.join(PACKAGE_ROOT, 'package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return pkg.version;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Check if a directory has a WordPress Agent Kit installation.
+ */
+export function isKitInstalled(targetDir, platform) {
+    const manifestPath = getManifestPath(targetDir, platform);
+    if (fs.existsSync(manifestPath))
+        return true;
+    const platformFolder = PLATFORM_FOLDERS[platform];
+    const targetPlatform = path.join(targetDir, platformFolder);
+    return fs.existsSync(targetPlatform);
+}

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 ../

package/dist/utils/run.js

@@ -11,7 +11,7 @@ export function run(command, args, cwd = process.cwd()) {
     const result = spawnSync(command, args, {
         cwd,
         stdio: 'inherit',
-        shell: process.platform === 'win32'
+        shell: process.platform === 'win32',
     });
     if (result.status !== 0) {
         console.error(`Command failed with status ${result.status}: ${command} ${args.join(' ')}`);