@phuetz/code-buddy 1.6.1 → 2.1.0

package/dist/commands/handlers/backup-handlers.js

@@ -3,63 +3,318 @@
  *
  * Native Engine v2026.3.8 alignment: `buddy backup create/verify/list/restore`
  * Local backup management for `.codebuddy/` configuration and workspace data.
+ * HOMEBACKUP1: Added --profile support for home profile backup with strict whitelist.
  */
-import { existsSync, mkdirSync, readdirSync, statSync, readFileSync } from 'fs';
-import { join, basename } from 'path';
+import { existsSync, lstatSync, mkdirSync, readdirSync, statSync, readFileSync, writeFileSync, copyFileSync, } from 'fs';
+import { join, basename, dirname, resolve, relative, isAbsolute, sep, win32 } from 'path';
 import { homedir } from 'os';
 import { createHash } from 'crypto';
 /** Default backup directory */
 const BACKUP_DIR = join(homedir(), '.codebuddy', 'backups');
+// HOMEBACKUP1: Profile backup configuration
+/** Default max file size for profile backups (5 MB) */
+export const DEFAULT_MAX_FILE_SIZE = 5 * 1024 * 1024; // 5 Mo
+/** Default total backup size limit (200 MB) */
+export const DEFAULT_MAX_TOTAL_SIZE = 200 * 1024 * 1024; // 200 Mo
+/** Get current home profile directory (~/.codebuddy) */
+export function getHomeProfileDir() {
+    return join(homedir(), '.codebuddy');
+}
+/** Home profile directory */
+export const HOME_PROFILE_DIR = getHomeProfileDir();
+/**
+ * Whitelist patterns for home profile backup.
+ * These are relative paths from the home profile directory.
+ * Only files matching these patterns will be considered for backup.
+ */
+export const PROFILE_BACKUP_WHITELIST = [
+    'settings.json',
+    'user-settings.json',
+    'memory.md',
+    'CODEBUDDY_MEMORY.md',
+    'reminders.json',
+    'snoozes.json',
+    'pending-acks.json',
+    'speech-hotwords.txt',
+    'mcp.json',
+    'identity-links.json',
+    // JSON files in personas directory (no images)
+    'personas/*.json',
+    // SKILL.md files in skills directory
+    'skills/**/SKILL.md',
+    // Self-improvement store
+    'self-improvement/store/',
+    // Collective ledger
+    'collective/ckg-ledger.jsonl',
+];
+/**
+ * Blacklist patterns for home profile backup - ABSOLUTE.
+ * Files matching these patterns will NEVER be backed up, even if explicitly requested.
+ * These patterns are checked against the filename (not path).
+ */
+export const PROFILE_BACKUP_BLACKLIST = [
+    '*.env',
+    '*auth*',
+    'credentials*',
+    '*token*',
+    '*secret*',
+    '*.enc',
+];
+/**
+ * Check if a filename matches any blacklist pattern.
+ * Blacklist matching is case-insensitive.
+ */
+export function isBlacklisted(filename) {
+    const lowerFilename = filename.toLowerCase();
+    for (const pattern of PROFILE_BACKUP_BLACKLIST) {
+        const lowerPattern = pattern.toLowerCase();
+        if (lowerPattern.startsWith('*') && lowerPattern.endsWith('*')) {
+            const middle = lowerPattern.slice(1, -1);
+            if (lowerFilename.includes(middle))
+                return true;
+        }
+        else if (lowerPattern.startsWith('*')) {
+            const suffix = lowerPattern.slice(1);
+            if (lowerFilename.endsWith(suffix))
+                return true;
+        }
+        else if (lowerPattern.endsWith('*')) {
+            const prefix = lowerPattern.slice(0, -1);
+            if (lowerFilename.startsWith(prefix))
+                return true;
+        }
+        else {
+            if (lowerFilename === lowerPattern)
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Simple string replacement for backslashes
+ */
+function normalizePathForMatching(path) {
+    let result = '';
+    for (let i = 0; i < path.length; i++) {
+        if (path[i] === '\\') {
+            result += '/';
+        }
+        else {
+            result += path[i];
+        }
+    }
+    return result;
+}
+/**
+ * Glob pattern matching for whitelist
+ */
+function matchesPattern(path, pattern) {
+    const normalizedPath = normalizePathForMatching(path);
+    const normalizedPattern = normalizePathForMatching(pattern);
+    // Handle directory patterns
+    if (normalizedPattern.endsWith('/')) {
+        const dirPrefix = normalizedPattern.slice(0, -1);
+        return normalizedPath === dirPrefix || normalizedPath.startsWith(dirPrefix + '/');
+    }
+    // Handle **/ patterns
+    if (normalizedPattern.includes('**/')) {
+        const parts = normalizedPattern.split('**/');
+        const prefix = parts[0] || '';
+        const suffix = parts[1] || '';
+        if (prefix && !normalizedPath.startsWith(prefix))
+            return false;
+        if (suffix && !normalizedPath.endsWith(suffix))
+            return false;
+        return true;
+    }
+    // Handle * patterns (single-segment wildcards)
+    if (normalizedPattern.includes('*')) {
+        const escaped = normalizedPattern.replace(/\./g, '\\.').replace(/\*/g, '[^/]*');
+        const regex = new RegExp(`^${escaped}$`);
+        return regex.test(normalizedPath);
+    }
+    // Exact match
+    return normalizedPath === normalizedPattern;
+}
+export function isWhitelisted(relativePath) {
+    const base = basename(relativePath);
+    if (isBlacklisted(base))
+        return false;
+    for (const pattern of PROFILE_BACKUP_WHITELIST) {
+        if (matchesPattern(relativePath, pattern)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Determine whether a directory relative path could contain whitelisted files.
+ * Avoids descending into huge 1.3TB directories like personas/ (images), runtimes/, etc.
+ */
+function canContainWhitelistedFiles(dirRel) {
+    const normDir = normalizePathForMatching(dirRel).replace(/\/+$/, '');
+    const dirBase = basename(normDir);
+    if (isBlacklisted(dirBase))
+        return false;
+    for (const pattern of PROFILE_BACKUP_WHITELIST) {
+        const normPattern = normalizePathForMatching(pattern);
+        if (normPattern.endsWith('/')) {
+            const patternDir = normPattern.slice(0, -1);
+            if (patternDir === normDir || patternDir.startsWith(normDir + '/') || normDir.startsWith(patternDir + '/')) {
+                return true;
+            }
+        }
+        else if (normPattern.includes('**/')) {
+            const basePrefix = normPattern.split('**/')[0].replace(/\/+$/, '');
+            if (basePrefix === normDir || basePrefix.startsWith(normDir + '/') || normDir.startsWith(basePrefix + '/')) {
+                return true;
+            }
+        }
+        else if (normPattern.includes('/')) {
+            const segments = normPattern.split('/');
+            const patternDir = segments.slice(0, -1).join('/');
+            if (patternDir === normDir || patternDir.startsWith(normDir + '/')) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
 /**
  * Handle `buddy backup <subcommand>` / `/backup`
  */
 export async function handleBackup(args, _context) {
     const parts = args.trim().split(/\s+/);
     const subcommand = parts[0]?.toLowerCase() || 'list';
+    // HOMEBACKUP1: Extract profile-related flags that apply to all subcommands
+    const profileMode = parts.includes('--home') || parts.includes('--home-profile') || parts.includes('--profile');
+    const scopeIndex = parts.indexOf('--scope');
+    const scopeValue = scopeIndex >= 0 && scopeIndex + 1 < parts.length
+        ? parts[scopeIndex + 1]?.toLowerCase()
+        : undefined;
+    const dryRun = parts.includes('--dry-run');
     switch (subcommand) {
         case 'create':
-            return handleBackupCreate(parts.slice(1));
+            return handleBackupCreate(parts.slice(1), { profileMode, scope: scopeValue, dryRun });
         case 'verify':
-            return handleBackupVerify(parts.slice(1));
+            return handleBackupVerify(parts.slice(1), { profileMode, scope: scopeValue });
         case 'list':
-            return handleBackupList();
+            return handleBackupList(parts.slice(1));
         case 'restore':
-            return handleBackupRestore(parts.slice(1));
+            return handleBackupRestore(parts.slice(1), { profileMode, scope: scopeValue });
         default:
             return {
                 handled: true,
-                response: `Unknown backup subcommand: ${subcommand}\nUsage: backup create|verify|list|restore`,
+                exitCode: 1,
+                response: `Unknown backup subcommand: ${subcommand}\nUsage: backup create|verify|list|restore [--home] [--scope home|project|both] [--dry-run]`,
             };
     }
 }
 /**
  * Create a backup of .codebuddy/ directory
  */
-async function handleBackupCreate(flags) {
+async function handleBackupCreate(flags, profileOpts) {
     const onlyConfig = flags.includes('--only-config');
     const noWorkspace = flags.includes('--no-include-workspace');
     const outputIdx = flags.indexOf('--output');
     const outputPath = outputIdx >= 0 ? flags[outputIdx + 1] : undefined;
-    const cwd = process.cwd();
-    const sourcePath = join(cwd, '.codebuddy');
-    if (!existsSync(sourcePath)) {
+    // HOMEBACKUP1: Profile backup options
+    const doProfileBackup = profileOpts?.profileMode || false;
+    const scope = profileOpts?.scope || (doProfileBackup ? 'home' : 'project');
+    const dryRun = profileOpts?.dryRun || false;
+    // Validate scope
+    if (scope && !['home', 'project', 'both'].includes(scope)) {
         return {
             handled: true,
-            response: 'No .codebuddy/ directory found in current project.',
+            exitCode: 1,
+            response: `Invalid scope: ${scope}. Must be one of: home, project, both`,
+        };
+    }
+    // Determine source paths based on scope
+    const sources = [];
+    const homeProfileDir = getHomeProfileDir();
+    if (scope === 'both' || scope === 'project') {
+        const cwd = process.cwd();
+        const sourcePath = join(cwd, '.codebuddy');
+        if (existsSync(sourcePath)) {
+            sources.push({ path: sourcePath, type: 'project' });
+        }
+    }
+    if (scope === 'both' || scope === 'home') {
+        if (existsSync(homeProfileDir)) {
+            sources.push({ path: homeProfileDir, type: 'home' });
+        }
+    }
+    if (sources.length === 0) {
+        return {
+            handled: true,
+            exitCode: 1,
+            response: scope === 'home'
+                ? `No home profile directory found at ${homeProfileDir}.`
+                : `No .codebuddy/ directory found at ${join(process.cwd(), '.codebuddy')}. Create one with \`buddy --init\` first.`,
         };
     }
     // Ensure backup directory exists
     const backupDir = outputPath ? join(outputPath) : BACKUP_DIR;
-    if (!existsSync(backupDir)) {
-        mkdirSync(backupDir, { recursive: true });
+    try {
+        if (!existsSync(backupDir)) {
+            mkdirSync(backupDir, { recursive: true });
+        }
+    }
+    catch (err) {
+        return {
+            handled: true,
+            exitCode: 1,
+            response: describeBackupIoError(err, `create the backup directory ${backupDir}`),
+        };
+    }
+    // HOMEBACKUP1: Collect files from all sources
+    const allSkipped = [];
+    const allFiles = [];
+    const sourceDescriptions = [];
+    for (const source of sources) {
+        const basePath = source.path;
+        if (source.type === 'home') {
+            // For home profile, use profile-specific collection with whitelist/blacklist
+            const profileFiles = collectProfileFiles(basePath, homeProfileDir, {
+                maxFileSize: DEFAULT_MAX_FILE_SIZE,
+                maxTotalSize: DEFAULT_MAX_TOTAL_SIZE,
+            }, allSkipped);
+            allFiles.push(...profileFiles.files);
+            sourceDescriptions.push(`${homeProfileDir} (profile)`);
+        }
+        else {
+            // For project, use existing collection
+            const projectFiles = collectFiles(basePath, basePath, { onlyConfig, noWorkspace }, allSkipped);
+            allFiles.push(...projectFiles);
+            sourceDescriptions.push(scope === 'both'
+                ? `${basePath} (current project .codebuddy/)`
+                : `${basePath} (current project .codebuddy/; does not include ~/.codebuddy; use --home for home profile)`);
+        }
+    }
+    if (allFiles.length === 0) {
+        const sourceList = sourceDescriptions.join(', ');
+        return {
+            handled: true,
+            exitCode: 1,
+            response: `No files to back up in ${sourceList}. ` +
+                `The directories are empty, or every file was skipped.` + (dryRun ? ' (dry run)' : ''),
+        };
+    }
+    // HOMEBACKUP1: Check total size against limit
+    const totalSize = allFiles.reduce((sum, f) => sum + f.size, 0);
+    if (totalSize > DEFAULT_MAX_TOTAL_SIZE) {
+        return {
+            handled: true,
+            exitCode: 1,
+            response: `Total backup size (${formatBackupSize(totalSize)}) exceeds maximum allowed size of ${formatBackupSize(DEFAULT_MAX_TOTAL_SIZE)}`,
+        };
     }
-    // Collect files to backup
-    const files = collectFiles(sourcePath, sourcePath, { onlyConfig, noWorkspace });
     // Build manifest
     const manifest = {
-        version: '1.0.0',
+        version: '2.0.0', // HOMEBACKUP1: Bumped version for profile support
         createdAt: new Date().toISOString(),
-        files: files.map(f => ({
+        files: allFiles.map(f => ({
             path: f.relativePath,
             size: f.size,
             checksum: f.checksum,
@@ -68,39 +323,83 @@ async function handleBackupCreate(flags) {
             onlyConfig,
             includeWorkspace: !noWorkspace,
         },
+        scope: scope !== 'project' ? scope : undefined,
+        profile: doProfileBackup || scope === 'home' || scope === 'both' ? true : undefined,
     };
     // Generate backup filename
     const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
-    const backupName = `codebuddy-backup-${timestamp}.json`;
+    const scopeSuffix = scope === 'home' ? '-profile' : scope === 'both' ? '-full' : '';
+    const backupName = `codebuddy-backup-${timestamp}${scopeSuffix}.json`;
     const backupPath = join(backupDir, backupName);
+    // HOMEBACKUP1: Dry run mode - list what would be backed up without writing
+    if (dryRun) {
+        const sourceList = sourceDescriptions.join(', ');
+        const fileList = allFiles.length <= 12
+            ? ` (${allFiles.map((file) => file.relativePath).join(', ')})`
+            : '';
+        const skippedLine = allSkipped.length === 0
+            ? ''
+            : `Skipped: ${allSkipped.length} (${allSkipped.map((item) => `${item.relativePath}: ${item.reason}`).join('; ')})`;
+        return {
+            handled: true,
+            response: [
+                `[DRY RUN] Would create backup: ${backupPath}`,
+                `Source: ${sourceList}`,
+                `Files: ${allFiles.length}${fileList}`,
+                `Size: ${formatBackupSize(totalSize)}`,
+                skippedLine,
+                onlyConfig ? '(config only)' : '',
+                noWorkspace ? '(workspace excluded)' : '',
+                `Actual scope: ${scope}`,
+            ].filter(Boolean).join('\n'),
+        };
+    }
     // Write backup as JSON (portable, no tar dependency needed)
     const backupData = {
         manifest,
-        totalSize: files.reduce((sum, f) => sum + f.size, 0),
-        fileCount: files.length,
+        files: allFiles.map(f => ({ path: f.relativePath, content: f.content.toString('base64') })),
+        totalSize,
+        fileCount: allFiles.length,
     };
-    const { writeFileSync } = await import('fs');
-    writeFileSync(backupPath, JSON.stringify(backupData, null, 2));
-    const totalSizeKB = Math.round(backupData.totalSize / 1024);
+    try {
+        writeFileSync(backupPath, JSON.stringify(backupData, null, 2));
+    }
+    catch (err) {
+        return {
+            handled: true,
+            exitCode: 1,
+            response: describeBackupIoError(err, `write backup ${backupPath}`),
+        };
+    }
+    const fileList = allFiles.length <= 12
+        ? ` (${allFiles.map((file) => file.relativePath).join(', ')})`
+        : '';
+    const skippedLine = allSkipped.length === 0
+        ? ''
+        : `Skipped: ${allSkipped.length} (${allSkipped.map((item) => `${item.relativePath}: ${item.reason}`).join('; ')})`;
     return {
         handled: true,
         response: [
             `Backup created: ${backupPath}`,
-            `Files: ${files.length}`,
-            `Size: ${totalSizeKB} KB`,
+            `Source: ${sourceDescriptions.join(', ')}`,
+            `Files: ${allFiles.length}${fileList}`,
+            `Size: ${formatBackupSize(totalSize)}`,
+            skippedLine,
             onlyConfig ? '(config only)' : '',
             noWorkspace ? '(workspace excluded)' : '',
+            doProfileBackup ? `(profile backup: scope=${scope})` : '',
         ].filter(Boolean).join('\n'),
     };
 }
 /**
  * Verify a backup file
  */
-async function handleBackupVerify(args) {
+async function handleBackupVerify(args, _profileOpts) {
     const filePath = args[0];
     if (!filePath) {
         return {
             handled: true,
+            exitCode: 1,
             response: 'Usage: backup verify <file>',
         };
     }
@@ -108,6 +407,7 @@ async function handleBackupVerify(args) {
     if (!existsSync(fullPath)) {
         return {
             handled: true,
+            exitCode: 1,
             response: `Backup file not found: ${fullPath}`,
         };
     }
@@ -117,7 +417,32 @@ async function handleBackupVerify(args) {
         if (!manifest || !manifest.version || !Array.isArray(manifest.files)) {
             return {
                 handled: true,
-                response: `Invalid backup: missing or corrupt manifest`,
+                exitCode: 1,
+                response: `Invalid backup ${fullPath}: missing or corrupt manifest`,
+            };
+        }
+        if (!isSupportedBackupVersion(manifest.version)) {
+            return {
+                handled: true,
+                exitCode: 1,
+                response: `Invalid backup ${fullPath}: unsupported backup format (need version 1.x or 2.x), got ${manifest.version}`,
+            };
+        }
+        for (const file of manifest.files) {
+            if (isBlacklisted(basename(file.path))) {
+                return {
+                    handled: true,
+                    exitCode: 1,
+                    response: `Invalid backup ${fullPath}: secret file in archive is forbidden: ${file.path}`,
+                };
+            }
+        }
+        const payloadError = verifyArchivePayloads(manifest, data.files);
+        if (payloadError) {
+            return {
+                handled: true,
+                exitCode: 1,
+                response: `Invalid backup ${fullPath}: ${payloadError}`,
             };
         }
         return {
@@ -135,21 +460,27 @@ async function handleBackupVerify(args) {
     catch (err) {
         return {
             handled: true,
-            response: `Backup corrupt or unreadable: ${err.message}`,
+            exitCode: 1,
+            response: describeUnreadableBackup(fullPath, err),
         };
     }
 }
 /**
  * List available backups
  */
-async function handleBackupList() {
-    if (!existsSync(BACKUP_DIR)) {
+async function handleBackupList(args = []) {
+    const outputIdx = args.indexOf('--output');
+    const customOutput = outputIdx >= 0 ? args[outputIdx + 1] : undefined;
+    const backupDir = customOutput
+        ? join(customOutput)
+        : BACKUP_DIR;
+    if (!existsSync(backupDir)) {
         return {
             handled: true,
             response: 'No backups found.',
         };
     }
-    const files = readdirSync(BACKUP_DIR)
+    const files = readdirSync(backupDir)
         .filter(f => f.startsWith('codebuddy-backup-') && f.endsWith('.json'))
         .sort()
         .reverse();
@@ -160,63 +491,334 @@ async function handleBackupList() {
         };
     }
     const lines = files.map(f => {
-        const fullPath = join(BACKUP_DIR, f);
+        const fullPath = join(backupDir, f);
         const stat = statSync(fullPath);
-        const sizeKB = Math.round(stat.size / 1024);
-        return `  ${f}  (${sizeKB} KB, ${stat.mtime.toLocaleDateString()})`;
+        return `  ${f}  (${formatBackupSize(stat.size)}, ${stat.mtime.toLocaleDateString()})`;
     });
     return {
         handled: true,
-        response: `Backups in ${BACKUP_DIR}:\n${lines.join('\n')}`,
+        response: `Backups in ${backupDir}:\n${lines.join('\n')}`,
     };
 }
 /**
  * Restore from a backup (with confirmation message)
  */
-async function handleBackupRestore(args) {
-    const filePath = args[0];
+async function handleBackupRestore(args, profileOpts) {
+    const confirm = args.includes('--confirm');
+    const filePath = args.find((arg) => arg !== '--confirm' && !arg.startsWith('--'));
     if (!filePath) {
         return {
             handled: true,
-            response: 'Usage: backup restore <file>',
+            exitCode: 1,
+            response: 'Usage: backup restore <file> [--confirm] [--home] [--scope home|project|both]',
         };
     }
     const fullPath = resolveBackupPath(filePath);
     if (!existsSync(fullPath)) {
         return {
             handled: true,
+            exitCode: 1,
             response: `Backup file not found: ${fullPath}`,
         };
     }
+    // HOMEBACKUP1: Determine restore scope from manifest or flags
+    let restoreScope = profileOpts?.scope;
     try {
         const data = JSON.parse(readFileSync(fullPath, 'utf-8'));
         const manifest = data.manifest;
         if (!manifest || !Array.isArray(manifest.files)) {
             return {
                 handled: true,
-                response: 'Invalid backup file.',
+                exitCode: 1,
+                response: `Invalid backup ${fullPath}: missing or corrupt manifest`,
+            };
+        }
+        // HOMEBACKUP1: Support version 2.x for profile backups
+        if (!isSupportedBackupVersion(manifest.version) && manifest.version !== '2.0.0') {
+            return {
+                handled: true,
+                exitCode: 1,
+                response: `Invalid backup ${fullPath}: unsupported backup format (need version 1.x or 2.x), got ${String(manifest.version)}`,
+            };
+        }
+        // HOMEBACKUP1: Determine scope from manifest if not specified in flags
+        const manifestScope = manifest.scope;
+        const manifestProfile = manifest.profile;
+        restoreScope = restoreScope || manifestScope || (manifestProfile ? 'home' : 'project');
+        // Determine destination based on scope
+        let destRoots = [];
+        if (restoreScope === 'both' || restoreScope === 'project') {
+            const projectDest = resolve(join(process.cwd(), '.codebuddy'));
+            destRoots.push(projectDest);
+        }
+        if (restoreScope === 'both' || restoreScope === 'home') {
+            destRoots.push(getHomeProfileDir());
+        }
+        if (destRoots.length === 0) {
+            destRoots = [resolve(join(process.cwd(), '.codebuddy'))];
+        }
+        // TypeScript can't infer that destRoots[0] is defined, so we need to assert it
+        const destRoot = destRoots[0];
+        let extras = [];
+        try {
+            extras = extraFilesNotInArchive(destRoot, manifest.files.map((file) => file.path));
+        }
+        catch {
+            extras = [];
+        }
+        if (!confirm) {
+            return {
+                handled: true,
+                response: [
+                    `Ready to restore backup: ${basename(fullPath)}`,
+                    `Created: ${manifest.createdAt}`,
+                    `Files: ${manifest.files.length}`,
+                    '',
+                    `This merges into ${destRoot}: archive files are overwritten, extra files are left in place.`,
+                    formatExtraFilesLine(extras) || 'No extra files are present.',
+                    'To confirm, run: backup restore <file> --confirm',
+                ].join('\n'),
+            };
+        }
+        for (const manifestFile of manifest.files) {
+            if (isBlacklisted(basename(manifestFile.path))) {
+                return {
+                    handled: true,
+                    exitCode: 1,
+                    response: `Cannot restore ${fullPath}: secret file in archive is forbidden: ${manifestFile.path}`,
+                };
+            }
+        }
+        const payloadError = verifyArchivePayloads(manifest, data.files);
+        if (payloadError) {
+            return {
+                handled: true,
+                exitCode: 1,
+                response: `Cannot restore ${fullPath}: ${payloadError}`,
+            };
+        }
+        const archiveFiles = data.files;
+        try {
+            mkdirSync(destRoot, { recursive: true });
+            const destinations = new Map();
+            for (const manifestFile of manifest.files) {
+                const dest = resolveRestoreDestination(destRoot, manifestFile.path);
+                if (!dest) {
+                    return {
+                        handled: true,
+                        exitCode: 1,
+                        response: `Cannot restore ${fullPath}: path escapes destination: ${manifestFile.path}`,
+                    };
+                }
+                destinations.set(manifestFile.path, dest);
+            }
+            for (const [archivePath, dest] of destinations) {
+                const safetyError = getRestorePathSafetyError(destRoot, dest);
+                if (safetyError) {
+                    return {
+                        handled: true,
+                        exitCode: 1,
+                        response: `Cannot restore ${fullPath}: unsafe destination for ${archivePath}: ${safetyError}`,
+                    };
+                }
+            }
+            const restored = [];
+            for (const manifestFile of manifest.files) {
+                const archiveFile = archiveFiles.find((file) => file.path === manifestFile.path);
+                if (!archiveFile) {
+                    return {
+                        handled: true,
+                        exitCode: 1,
+                        response: `Cannot restore ${fullPath}: archive payload is missing ${manifestFile.path}`,
+                    };
+                }
+                const content = Buffer.from(archiveFile.content, 'base64');
+                const dest = destinations.get(manifestFile.path);
+                mkdirSync(dirname(dest), { recursive: true });
+                const safetyError = getRestorePathSafetyError(destRoot, dest);
+                if (safetyError) {
+                    return {
+                        handled: true,
+                        exitCode: 1,
+                        response: `Cannot restore ${fullPath}: unsafe destination for ${manifestFile.path}: ${safetyError}`,
+                    };
+                }
+                if (existsSync(dest)) {
+                    try {
+                        copyFileSync(dest, `${dest}.bak`);
+                    }
+                    catch {
+                        // Ignore backup copy failure if unable to write .bak
+                    }
+                }
+                writeFileSync(dest, content);
+                const reread = readFileSync(dest);
+                const expectedChecksum = fileChecksum(content);
+                const actualChecksum = fileChecksum(reread);
+                if (actualChecksum !== expectedChecksum || actualChecksum !== manifestFile.checksum) {
+                    return {
+                        handled: true,
+                        exitCode: 1,
+                        response: `Restore verification failed for ${manifestFile.path}: on-disk hash does not match the archive`,
+                    };
+                }
+                restored.push(manifestFile.path);
+            }
+            return {
+                handled: true,
+                response: [
+                    `Restored backup: ${basename(fullPath)}`,
+                    `Files: ${restored.length}`,
+                    `Verified: sha256 match for ${restored.length} file(s)`,
+                    extras.length === 0
+                        ? 'Merged: no extra files were present in .codebuddy/.'
+                        : `Merged: ${formatExtraFilesLine(extras)}`,
+                ].join('\n'),
+            };
+        }
+        catch (err) {
+            return {
+                handled: true,
+                exitCode: 1,
+                response: describeBackupIoError(err, `write restored files from ${fullPath}`),
             };
         }
-        return {
-            handled: true,
-            response: [
-                `Ready to restore backup: ${basename(fullPath)}`,
-                `Created: ${manifest.createdAt}`,
-                `Files: ${manifest.files.length}`,
-                '',
-                'This will overwrite current .codebuddy/ configuration.',
-                'To confirm, run: backup restore <file> --confirm',
-            ].join('\n'),
-        };
     }
     catch (err) {
         return {
             handled: true,
-            response: `Failed to read backup: ${err.message}`,
+            exitCode: 1,
+            response: describeUnreadableBackup(fullPath, err),
         };
     }
 }
-function collectFiles(dir, base, opts) {
+function fileChecksum(content) {
+    return createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+/** Dummy dest used only to decide whether an archive path would escape on restore. */
+const VERIFY_PATH_ROOT = resolve('/codebuddy-backup-dest');
+function isSupportedBackupVersion(version) {
+    return typeof version === 'string' && (/^1(\.|$)/.test(version) || /^2(\.|$)/.test(version));
+}
+function formatBackupSize(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return '0 B';
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024) {
+        const kb = bytes / 1024;
+        return kb < 10 ? `${kb.toFixed(1)} KB` : `${Math.round(kb)} KB`;
+    }
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function describeUnreadableBackup(fullPath, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (/JSON|Unexpected token|Unterminated|not valid JSON/i.test(message)) {
+        return `This file is not a readable Code Buddy backup (truncated or not JSON): ${fullPath}`;
+    }
+    return `Cannot read backup ${fullPath}: ${message}`;
+}
+function describeBackupIoError(err, action) {
+    const e = err;
+    const target = e.path ? ` (${e.path})` : '';
+    if (e.code === 'ENOSPC') {
+        return `Cannot ${action}: no space left on the device${target}.`;
+    }
+    if (e.code === 'EACCES' || e.code === 'EPERM') {
+        return `Cannot ${action}: permission denied${target}.`;
+    }
+    if (e.code === 'ENOTDIR') {
+        return `Cannot ${action}: the output path is not a directory${target}.`;
+    }
+    if (e.code === 'EISDIR') {
+        return `Cannot ${action}: expected a file, got a directory${target}.`;
+    }
+    return `Cannot ${action}: ${e.message ?? String(err)}`;
+}
+/** True when `candidate` is destRoot itself or a file/dir under it. */
+function isInsideDestRoot(destRoot, candidate) {
+    const rel = relative(destRoot, candidate);
+    return rel === '' || (rel !== '..' &&
+        !rel.startsWith(`..${sep}`) &&
+        !isAbsolute(rel));
+}
+/** Reject symlinks in the destination path before any archive bytes are written. */
+function getRestorePathSafetyError(destRoot, candidate) {
+    const root = resolve(destRoot);
+    const dest = resolve(candidate);
+    if (!isInsideDestRoot(root, dest))
+        return 'path escapes destination';
+    const relativePath = relative(root, dest);
+    const segments = relativePath === '' ? [] : relativePath.split(sep);
+    let current = root;
+    for (let index = -1; index < segments.length; index++) {
+        if (index >= 0)
+            current = join(current, segments[index]);
+        const stat = lstatSync(current, { throwIfNoEntry: false });
+        if (!stat)
+            continue;
+        if (stat.isSymbolicLink())
+            return `symbolic link is forbidden: ${current}`;
+        if (index < segments.length - 1 && !stat.isDirectory()) {
+            return `path component is not a directory: ${current}`;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve an archive entry against destRoot. Returns null when the path
+ * is absolute, contains a NUL, uses win32 separators to walk out, or
+ * resolves outside destRoot (the `../../etc/x` class of restores).
+ */
+export function resolveRestoreDestination(destRoot, archivePath) {
+    if (typeof archivePath !== 'string' || archivePath.length === 0)
+        return null;
+    if (archivePath.includes('\0'))
+        return null;
+    if (isAbsolute(archivePath) || win32.isAbsolute(archivePath))
+        return null;
+    // Archives may carry Windows separators. Treat `\` as `/` so `..\..\etc\x`
+    // cannot land as a literal filename on POSIX or a traversal on win32.
+    const normalized = archivePath.replace(/\\/g, '/');
+    if (normalized !== archivePath && (isAbsolute(normalized) || win32.isAbsolute(normalized))) {
+        return null;
+    }
+    const root = resolve(destRoot);
+    const dest = resolve(root, normalized);
+    if (!isInsideDestRoot(root, dest))
+        return null;
+    return dest;
+}
+function verifyArchivePayloads(manifest, files) {
+    const archiveFiles = files;
+    if (manifest.files.length === 0 || !Array.isArray(archiveFiles) || archiveFiles.length === 0) {
+        return 'archive is empty: no file payloads found';
+    }
+    if (archiveFiles.length !== manifest.files.length) {
+        return 'archive payload does not match the manifest';
+    }
+    for (const manifestFile of manifest.files) {
+        if (!resolveRestoreDestination(VERIFY_PATH_ROOT, manifestFile.path)) {
+            return `path escapes destination: ${manifestFile.path}`;
+        }
+        const archiveFile = archiveFiles.find((file) => file.path === manifestFile.path);
+        if (!archiveFile || typeof archiveFile.content !== 'string') {
+            return `archive payload is missing ${manifestFile.path}`;
+        }
+        const content = Buffer.from(archiveFile.content, 'base64');
+        if (content.toString('base64') !== archiveFile.content) {
+            return `archive payload is not valid base64: ${manifestFile.path}`;
+        }
+        if (content.length !== manifestFile.size) {
+            return `archive size mismatch: ${manifestFile.path}`;
+        }
+        if (fileChecksum(content) !== manifestFile.checksum) {
+            return `archive checksum mismatch: ${manifestFile.path}`;
+        }
+    }
+    return null;
+}
+function collectFiles(dir, base, opts, skipped = []) {
     const results = [];
     // Config-only patterns
     const configPatterns = ['settings.json', 'hooks.json', 'mcp.json', 'rules/'];
@@ -231,10 +833,14 @@ function collectFiles(dir, base, opts) {
             if (skipPatterns.some(p => relativePath.startsWith(p))) {
                 continue;
             }
+            if (typeof entry.isSymbolicLink === 'function' && entry.isSymbolicLink()) {
+                skipped.push({ relativePath, reason: 'symbolic link' });
+                continue;
+            }
             if (entry.isDirectory()) {
                 if (opts.noWorkspace && relativePath === 'knowledge')
                     continue;
-                results.push(...collectFiles(fullPath, base, opts));
+                results.push(...collectFiles(fullPath, base, opts, skipped));
             }
             else {
                 // Config-only mode: only include config files
@@ -243,15 +849,17 @@ function collectFiles(dir, base, opts) {
                 }
                 try {
                     const stat = statSync(fullPath);
-                    // Skip files larger than 1MB
-                    if (stat.size > 1024 * 1024)
+                    if (stat.size > 1024 * 1024) {
+                        skipped.push({ relativePath, reason: 'larger than 1 MB' });
                         continue;
+                    }
                     const content = readFileSync(fullPath);
-                    const checksum = createHash('sha256').update(content).digest('hex').slice(0, 16);
+                    const checksum = fileChecksum(content);
                     results.push({
                         relativePath,
                         size: stat.size,
                         checksum,
+                        content,
                     });
                 }
                 catch {
@@ -265,6 +873,125 @@ function collectFiles(dir, base, opts) {
     }
     return results;
 }
+function collectProfileFiles(dir, base, limits, skipped = []) {
+    const results = [];
+    let currentTotalSize = 0;
+    try {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = join(dir, entry.name);
+            const relativePath = fullPath.slice(base.length + 1).replace(/\\/g, '/');
+            // Skip directories that are not in whitelist
+            const isDir = typeof entry.isDirectory === 'function' && entry.isDirectory();
+            const isSymlink = typeof entry.isSymbolicLink === 'function' && entry.isSymbolicLink();
+            if (isSymlink) {
+                skipped.push({ relativePath, reason: 'symbolic link' });
+                continue;
+            }
+            // Always skip blacklisted files by name
+            const filename = entry.name;
+            if (isBlacklisted(filename)) {
+                skipped.push({ relativePath, reason: 'blacklisted (secret file)' });
+                continue;
+            }
+            if (isDir) {
+                if (canContainWhitelistedFiles(relativePath)) {
+                    const dirResult = collectProfileFiles(fullPath, base, limits, skipped);
+                    results.push(...dirResult.files);
+                    currentTotalSize += dirResult.totalSize;
+                }
+                else {
+                    skipped.push({ relativePath, reason: 'directory not in whitelist' });
+                    continue;
+                }
+            }
+            else {
+                // It's a file
+                if (!isWhitelisted(relativePath)) {
+                    skipped.push({ relativePath, reason: 'not in whitelist' });
+                    continue;
+                }
+                try {
+                    const stat = statSync(fullPath);
+                    // Check file size limit
+                    if (stat.size > limits.maxFileSize) {
+                        skipped.push({
+                            relativePath,
+                            reason: `larger than ${formatBackupSize(limits.maxFileSize)}`
+                        });
+                        continue;
+                    }
+                    // Read file content
+                    const content = readFileSync(fullPath);
+                    const checksum = fileChecksum(content);
+                    results.push({
+                        relativePath,
+                        size: stat.size,
+                        checksum,
+                        content,
+                    });
+                    currentTotalSize += stat.size;
+                }
+                catch {
+                    // Skip unreadable files
+                    skipped.push({ relativePath, reason: 'unreadable' });
+                }
+            }
+        }
+    }
+    catch {
+        // Skip unreadable directories
+    }
+    return { files: results, totalSize: currentTotalSize };
+}
+function listProfileRelativeFiles(root) {
+    const results = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const name = typeof entry === 'string' ? entry : entry?.name;
+            if (typeof name !== 'string' || name.length === 0)
+                continue;
+            const full = join(dir, name);
+            const rel = relative(root, full).replace(/\\/g, '/');
+            if (rel === '.backup-restore-staging' || rel.startsWith('.backup-restore-staging/'))
+                continue;
+            if (typeof entry !== 'object' || entry === null) {
+                results.push(rel);
+                continue;
+            }
+            if (typeof entry.isSymbolicLink === 'function' && entry.isSymbolicLink()) {
+                results.push(rel);
+                continue;
+            }
+            if (typeof entry.isDirectory === 'function' && entry.isDirectory())
+                walk(full);
+            else
+                results.push(rel);
+        }
+    };
+    if (!existsSync(root))
+        return [];
+    walk(root);
+    return results.sort();
+}
+function extraFilesNotInArchive(destRoot, archivePaths) {
+    const inArchive = new Set(archivePaths);
+    return listProfileRelativeFiles(destRoot).filter((filePath) => !inArchive.has(filePath));
+}
+function formatExtraFilesLine(extras) {
+    if (extras.length === 0)
+        return '';
+    const shown = extras.slice(0, 12);
+    const more = extras.length > 12 ? `; …and ${extras.length - 12} more` : '';
+    return `${extras.length} extra file(s) not in the archive will be left in place: ${shown.join(', ')}${more}`;
+}
 function resolveBackupPath(filePath) {
     if (filePath.includes('/') || filePath.includes('\\')) {
         return filePath;