fix: preserve current files during backup restore

[Timpan4]

Restore could overwrite current files in Merge mode, and bootstrap separately applied backup project configuration automatically. Normal restore now keeps current content and saves differing backup copies separately, using one resolved plan for preview and execution.

• Hash-check staged copies, preserve backup contents, and reuse stable recovered-file locations on reruns. Report restored, already-present, conflicting-copy-saved, skipped, and failed outcomes, with an Open recovered files action.
• Require preview and explicit confirmation for personal-file replacement and Use backup settings. Remove bootstrap's automatic configuration copy.
• Restore explicitly selected app state as a group with process checks, verified staging, and rollback. Preserve app metadata in backups and skip unclassified AppData.

The restore plan is reusable by #83; this does not implement its broader setup preview.

Validation: all 266 Pester tests pass, including isolated conflict, integrity, selection, rollback, and backup-metadata fixtures. Windows PowerShell 5.1 smoke checks passed for merge and replacement. No installed setup or personal data was changed.

Closes #36.

Summary by CodeRabbit

• New Features

  • Added structured backup restoration with Merge, Skip Existing, and Overwrite modes.
  • Added preview and WhatIf support, confirmation prompts for sensitive restores, recovery copies for conflicts, verification, rollback, and restore reports.
  • Added explicit application selection and checks that selected applications are closed before restoring state.
  • Added validation for application identities and process names in backup configurations.

• Bug Fixes

  • Repository setup no longer automatically overwrites current backup settings; settings can be restored explicitly.

• Documentation

  • Expanded restore guidance, conflict handling, selections, safety checks, and application-state behavior.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: de1d548b-20ee-4b1b-8e9b-f6c8a3e0d63e

📥 Commits

Reviewing files that changed from the base of the PR and between 24a23ef and 88a5d63.

📒 Files selected for processing (14)

• README.md
• bootstrap.ps1
• docs/BACKUP-FORMAT.md
• modules/BackupManifest.ps1
• modules/RestorePlan.ps1
• preflight-backup.ps1
• restore-backup.ps1
• tests/BackupHashes.Tests.ps1
• tests/BackupOutcomes.Tests.ps1
• tests/BackupRestore.Tests.ps1
• tests/CanonicalRepoRestore.Tests.ps1
• tests/PortableBackup.Tests.ps1
• tests/RestoreConflicts.Tests.ps1
• tests/RestoreProfile.Tests.ps1

---

📝 Walkthrough

Walkthrough

The pull request adds a shared restore-plan pipeline with conflict handling, verified file publication, explicit application-state restoration, and rollback. It separates repository cloning from backup-settings restoration and updates validation, documentation, and integration tests.

Changes

Restore pipeline

Layer / File(s)	Summary
Application metadata contracts modules/BackupManifest.ps1, preflight-backup.ps1, tests/BackupHashes.Tests.ps1	Application identifiers and exact process names are copied into manifests and validated.
Restore planning and execution modules/RestorePlan.ps1, tests/RestoreConflicts.Tests.ps1	The new pipeline plans file conflicts, preserves recovered copies, verifies hashes, supports preview and explicit selections, restores application roots, checks process state, and rolls back failed swaps.
Restore entry points and repository separation restore-backup.ps1, bootstrap.ps1, README.md, docs/BACKUP-FORMAT.md	The restore script delegates to the shared plan, supports explicit options and confirmation, writes recovery reports, and separates repository cloning from backup-settings restoration.
Integration and regression coverage tests/BackupOutcomes.Tests.ps1, tests/BackupRestore.Tests.ps1, tests/CanonicalRepoRestore.Tests.ps1, tests/PortableBackup.Tests.ps1, tests/RestoreProfile.Tests.ps1	Tests cover verified copy outcomes, retry behavior, updated restore parameters, and the removal of implicit repository-file restoration.

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant restore-backup.ps1
  participant New-RestorePlan
  participant Invoke-RestorePlan
  participant FileSystem
  User->>restore-backup.ps1: select manifest and restore options
  restore-backup.ps1->>New-RestorePlan: create verified restore plan
  New-RestorePlan->>FileSystem: inspect hashes and destinations
  User->>restore-backup.ps1: confirm required operation
  restore-backup.ps1->>Invoke-RestorePlan: execute plan
  Invoke-RestorePlan->>FileSystem: stage, verify, and publish changes
  Invoke-RestorePlan-->>restore-backup.ps1: return item statuses

Loading

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/preserve-current-restore-files

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}