wordpress-agent-kit 0.2.2 → 0.3.2

package/dist/lib/api.js

@@ -9,6 +9,7 @@ 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';
+import { computeChanges, isKitInstalled } from './updater.js';
 /**
  * Install the WordPress Agent Kit programmatically.
  */
@@ -16,15 +17,15 @@ 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;
+        const { targetDir, platform, force = false, dryRun = false, safe = true, backup = true, } = options;
         if (dryRun) {
-            return dryRunInstall(targetDir, platform, force);
+            return dryRunInstall(targetDir, platform, { force, safe, backup });
         }
         await withExitCode(async () => {
-            await installKit(targetDir, platform);
+            installKit(targetDir, platform, { force, safe, backup });
             return { success: true };
         });
-        const filesCreated = getInstalledFiles(targetDir, platform);
+        const filesCreated = getInstalledSummary(targetDir, platform);
         const durationMs = Date.now() - startTime;
         return formatter.success({
             targetDir,
@@ -33,6 +34,8 @@ export async function installKitApi(options) {
             filesSkipped: [],
             errors: [],
             durationMs,
+            isUpdate: isKitInstalled(targetDir, platform),
+            backupDir: null,
         });
     }
     catch (error) {
@@ -48,15 +51,66 @@ export async function installKitApi(options) {
 /**
  * Dry-run preview for install.
  */
-function dryRunInstall(targetDir, platform, force) {
+function dryRunInstall(targetDir, platform, options) {
+    const { force = false, safe = true } = options;
     const platformFolder = getPlatformFolder(platform);
+    const formatter = new OutputFormatter('json', 'install', '0.0.0');
+    // Use change-computation for safe updates on existing installations
+    if (safe && isKitInstalled(targetDir, platform)) {
+        const changes = computeChanges(targetDir, platform, force);
+        const actions = changes.map((c) => {
+            const target = path.join(targetDir, platformFolder, c.relativePath);
+            return {
+                type: c.action === 'created' ? 'create' : c.action === 'updated' ? 'update' : 'skip',
+                target,
+                description: `${c.action}: ${c.relativePath}${c.reason ? ` (${c.reason})` : ''}`,
+            };
+        });
+        // AGENTS.md check
+        const targetAgents = path.join(targetDir, 'AGENTS.md');
+        if (!fs.existsSync(targetAgents)) {
+            actions.push({
+                type: 'create',
+                target: targetAgents,
+                description: 'Create AGENTS.md from template',
+            });
+        }
+        else {
+            actions.push({
+                type: 'skip',
+                target: targetAgents,
+                description: 'AGENTS.md exists (preserved)',
+            });
+        }
+        return formatter.success({
+            wouldExecute: true,
+            actions,
+            summary: {
+                targetDir,
+                platform,
+                filesCreated: changes
+                    .filter((c) => c.action === 'created')
+                    .map((c) => path.join(platformFolder, c.relativePath)),
+                filesSkipped: changes
+                    .filter((c) => c.action === 'skipped' || c.action === 'conflict')
+                    .map((c) => `${path.join(platformFolder, c.relativePath)} (${c.reason})`),
+                errors: [],
+                durationMs: 0,
+                isUpdate: true,
+                backupDir: null,
+                conflicts: changes
+                    .filter((c) => c.action === 'conflict')
+                    .map((c) => path.join(platformFolder, c.relativePath)),
+            },
+        });
+    }
+    // Legacy dry-run for fresh installs
     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({
@@ -74,7 +128,6 @@ function dryRunInstall(targetDir, platform, force) {
             });
         }
     }
-    // AGENTS.template.md
     if (fs.existsSync(templatePath)) {
         actions.push({
             type: 'copy',
@@ -83,7 +136,6 @@ function dryRunInstall(targetDir, platform, force) {
             description: 'Copy AGENTS.template.md',
         });
     }
-    // AGENTS.md
     if (!fs.existsSync(targetAgents) || force) {
         if (fs.existsSync(templatePath)) {
             actions.push({
@@ -101,7 +153,7 @@ function dryRunInstall(targetDir, platform, force) {
             description: 'AGENTS.md exists (use --force to overwrite)',
         });
     }
-    return new OutputFormatter('json', 'install', '0.0.0').success({
+    return formatter.success({
         wouldExecute: true,
         actions,
         summary: {
@@ -111,6 +163,8 @@ function dryRunInstall(targetDir, platform, force) {
             filesSkipped: actions.filter((a) => a.type === 'update').map((a) => a.target),
             errors: [],
             durationMs: 0,
+            isUpdate: false,
+            backupDir: null,
         },
     });
 }
@@ -419,38 +473,50 @@ function getPlatformFolder(platform) {
     return folders[platform];
 }
 /**
- * Get list of files that would be/are installed.
+ * Get summary of installed files grouped by directory.
  */
-function getInstalledFiles(targetDir, platform) {
+function getInstalledSummary(targetDir, platform) {
     const platformFolder = getPlatformFolder(platform);
-    const files = [];
+    const summary = [];
     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 top-level entries for clean summary
+        const topEntries = fs.readdirSync(targetPlatform);
+        for (const entry of topEntries) {
+            const fullPath = path.join(targetPlatform, entry);
+            const stat = fs.statSync(fullPath);
+            if (stat.isDirectory()) {
+                let totalFiles = 0;
+                let totalDirs = 0;
+                function countAll(dir) {
+                    const items = fs.readdirSync(dir);
+                    for (const item of items) {
+                        const itemPath = path.join(dir, item);
+                        const s = fs.statSync(itemPath);
+                        if (s.isDirectory()) {
+                            totalDirs++;
+                            countAll(itemPath);
+                        }
+                        else {
+                            totalFiles++;
+                        }
+                    }
                 }
+                countAll(fullPath);
+                summary.push(`${platformFolder}/${entry}/ (${totalDirs + 1} dirs, ${totalFiles} files)`);
             }
         }
-        walk(targetPlatform);
     }
     const agentsPath = path.join(targetDir, 'AGENTS.md');
     if (fs.existsSync(agentsPath)) {
-        files.push('AGENTS.md');
+        summary.push('AGENTS.md');
     }
     const agentsTemplatePath = path.join(targetDir, 'AGENTS.template.md');
     if (fs.existsSync(agentsTemplatePath)) {
-        files.push('AGENTS.template.md');
+        summary.push('AGENTS.template.md');
     }
-    return files;
+    return summary;
 }
 export { ExitCode } from '../utils/exit-codes.js';
 export { OutputFormatter, createFormatter, parseOutputFormat } from '../utils/output.js';
+export { computeChanges, isKitInstalled, loadManifest, updateKit } from './updater.js';

package/dist/lib/installer.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { PACKAGE_ROOT } from '../utils/paths.js';
+import { updateKit } from './updater.js';
 /**
  * Platform-specific folder names
  */
@@ -13,21 +14,45 @@ export const PLATFORM_FOLDERS = {
 };
 /**
  * Installs the WordPress Agent Kit into the specified directory for a given platform.
- * Copies the platform-specific folder and AGENTS.md template.
+ * If the kit is already installed, uses safe update logic to preserve user modifications.
  *
- * @param {string} targetDir - The directory where the kit should be installed.
- * @param {Platform} platform - The target platform (github, cursor, claude, agent)
- * @returns {Promise<void>}
+ * @param targetDir - The directory where the kit should be installed.
+ * @param platform - The target platform (github, cursor, claude, agent, pi)
+ * @returns InstallKitResult with details of what was created/skipped
  */
-export async function installKit(targetDir, platform = 'github') {
+export function installKit(targetDir, platform = 'github', options = {}) {
+    const { force = false, backup = true, safe = true } = options;
+    // Check if kit is already installed
+    const isInstalled = isKitAlreadyInstalled(targetDir, platform);
+    // Use safe update for existing installations
+    if (isInstalled && safe) {
+        return safeUpdateInstall(targetDir, platform, { force, backup });
+    }
+    // Fresh install or fallback to full replacement
+    return fullInstall(targetDir, platform, force);
+}
+/**
+ * Check if kit is already installed for a platform.
+ */
+function isKitAlreadyInstalled(targetDir, platform) {
+    const platformFolder = PLATFORM_FOLDERS[platform];
+    const targetPlatform = path.join(targetDir, platformFolder);
+    return fs.existsSync(targetPlatform);
+}
+/**
+ * Full install (fresh or force-replace).
+ * Only used when no existing installation is detected or safe=false.
+ */
+function fullInstall(targetDir, platform, _force) {
     const platformFolder = PLATFORM_FOLDERS[platform];
-    console.log(`Installing WordPress Agent Kit (${platform}) into: ${targetDir}`);
     if (!fs.existsSync(targetDir)) {
         fs.mkdirSync(targetDir, { recursive: true });
     }
     const templatePath = path.join(PACKAGE_ROOT, 'AGENTS.template.md');
     const agentsPath = path.join(PACKAGE_ROOT, 'AGENTS.md');
     const sourceGithub = path.join(PACKAGE_ROOT, '.github');
+    const filesCreated = [];
+    const filesSkipped = [];
     // Copy platform-specific folder
     const targetPlatform = path.join(targetDir, platformFolder);
     if (fs.existsSync(targetPlatform)) {
@@ -39,18 +64,99 @@ export async function installKit(targetDir, platform = 'github') {
     else {
         throw new Error('Could not find source .github directory.');
     }
-    // Copy AGENTS.md
+    // Collect created files
+    const collectFiles = (dir, prefix) => {
+        if (!fs.existsSync(dir))
+            return;
+        const entries = fs.readdirSync(dir);
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry);
+            const stat = fs.statSync(fullPath);
+            if (stat.isDirectory()) {
+                collectFiles(fullPath, path.join(prefix, entry));
+            }
+            else {
+                filesCreated.push(path.join(prefix, entry));
+            }
+        }
+    };
+    collectFiles(targetPlatform, platformFolder);
+    // Copy AGENTS.md template
     const targetAgentsTemplate = path.join(targetDir, 'AGENTS.template.md');
     if (fs.existsSync(templatePath)) {
         fs.copyFileSync(templatePath, targetAgentsTemplate);
+        filesCreated.push('AGENTS.template.md');
     }
+    // Copy AGENTS.md (only if it doesn't already exist)
     const targetAgents = path.join(targetDir, 'AGENTS.md');
     if (!fs.existsSync(targetAgents)) {
         if (fs.existsSync(templatePath)) {
             fs.copyFileSync(templatePath, targetAgents);
+            filesCreated.push('AGENTS.md');
         }
         else if (fs.existsSync(agentsPath)) {
             fs.copyFileSync(agentsPath, targetAgents);
+            filesCreated.push('AGENTS.md');
         }
     }
+    else {
+        filesSkipped.push('AGENTS.md (already exists, preserved)');
+    }
+    return {
+        targetDir,
+        platform,
+        filesCreated,
+        filesSkipped,
+        errors: [],
+        isUpdate: false,
+        backupDir: null,
+    };
+}
+/**
+ * Safe update install using the updater module.
+ */
+function safeUpdateInstall(targetDir, platform, options) {
+    const updateOptions = {
+        targetDir,
+        platform,
+        force: options.force ?? false,
+        backup: options.backup ?? true,
+    };
+    const result = updateKit(updateOptions);
+    // Handle AGENTS.md separately (not part of the platform folder)
+    const filesSkipped = [];
+    const filesCreated = [...result.created];
+    const templatePath = path.join(PACKAGE_ROOT, 'AGENTS.template.md');
+    const targetAgentsTemplate = path.join(targetDir, 'AGENTS.template.md');
+    if (fs.existsSync(templatePath)) {
+        fs.copyFileSync(templatePath, targetAgentsTemplate);
+        // Don't add template to created list as it's always overwritten
+    }
+    const targetAgents = path.join(targetDir, 'AGENTS.md');
+    if (!fs.existsSync(targetAgents)) {
+        fs.copyFileSync(templatePath, targetAgents);
+        filesCreated.push('AGENTS.md (from template)');
+    }
+    else {
+        filesSkipped.push('AGENTS.md (preserved)');
+    }
+    return {
+        targetDir,
+        platform,
+        filesCreated: [...result.created, ...result.updated].map((f) => path.join(PLATFORM_FOLDERS[platform], f)),
+        filesSkipped: [
+            ...filesSkipped,
+            ...result.skipped.map((f) => {
+                const filePath = path.join(PLATFORM_FOLDERS[platform], f);
+                return `${filePath} (skipped - not tracked or user modified)`;
+            }),
+        ],
+        conflicts: result.conflicts.map((f) => {
+            const filePath = path.join(PLATFORM_FOLDERS[platform], f);
+            return `${filePath} (conflict - user modified, use --force to overwrite)`;
+        }),
+        errors: [],
+        isUpdate: true,
+        backupDir: result.backupDir,
+    };
 }

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);
+}