Add guarded update snapshots and rollback guidance

[LegacyAngel2K9]

Summary

• verify an extracted target release against its locked Composer platform requirements before any files change
• capture a protected pre-update snapshot containing .env, Composer state, metadata, and a WAL-safe SQLite backup or driver-specific database guidance
• prune old secret-bearing snapshots with a configurable retention limit
• run the existing Spatie health checks after updating and provide concrete rollback guidance on failure

Context

This is the final focused PR split from #2529, covering the update snapshot and rollback tooling requested during review. It is independent of the installer preflight PR.

Safety details

• Composer is resolved from --composer, a local composer.phar, or PATH; PATH availability is not assumed.
• Named database connections are resolved to their actual driver.
• SQLite snapshots use VACUUM INTO, including committed WAL data.
• Required writes, permissions, metadata, and rollback artifacts are validated before a snapshot is exposed.
• Snapshots are private (0700 directories and 0600 files) and retention defaults to three.

Validation

• vendor/bin/pest tests/Integration/Maintenance/UpdateSafetyTest.php — 6 passed, 19 assertions
• Pint — passed
• PHPStan — no errors

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 06497f39-ed89-44f6-9fe7-54b5a7a77831

📥 Commits

Reviewing files that changed from the base of the PR and between e832ebe and d4a5f36.

📒 Files selected for processing (8)

• app/Console/Commands/Maintenance/FinishUpdateCommand.php
• app/Console/Commands/Maintenance/PrepareUpdateCommand.php
• app/Data/UpdateSnapshotData.php
• app/Services/Maintenance/UpdateCompatibilityService.php
• app/Services/Maintenance/UpdateSnapshotService.php
• config/panel.php
• lang/en/commands.php
• tests/Integration/Maintenance/UpdateSafetyTest.php

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

Adds update preparation and completion commands. The workflow validates Composer platform requirements, captures protected application and database snapshots, prunes retained snapshots, and reports health-check failures with rollback guidance.

Changes

Update safety workflow

Layer / File(s)	Summary
Snapshot capture and validation app/Data/UpdateSnapshotData.php, app/Services/Maintenance/UpdateSnapshotService.php, config/panel.php, tests/Integration/Maintenance/UpdateSafetyTest.php	Adds snapshot data, artifact capture, SQLite backup handling, metadata, rollback guidance, validation, cleanup, retention, and integration coverage.
Compatibility validation and preparation app/Services/Maintenance/UpdateCompatibilityService.php, app/Console/Commands/Maintenance/PrepareUpdateCommand.php, tests/Integration/Maintenance/UpdateSafetyTest.php	Adds Composer resolution and platform checks. The preparation command validates options, creates a snapshot, and returns translated status messages.
Completion health reporting app/Console/Commands/Maintenance/FinishUpdateCommand.php, lang/en/commands.php	Adds health-check execution and failure reporting with the selected or latest snapshot rollback guide.

Sequence Diagram(s)

sequenceDiagram
  participant Operator
  participant PrepareUpdateCommand
  participant UpdateCompatibilityService
  participant Composer
  participant UpdateSnapshotService
  Operator->>PrepareUpdateCommand: provide update options
  PrepareUpdateCommand->>UpdateCompatibilityService: validate target requirements
  UpdateCompatibilityService->>Composer: run check-platform-reqs
  Composer-->>UpdateCompatibilityService: return compatibility result
  PrepareUpdateCommand->>UpdateSnapshotService: capture snapshot
  UpdateSnapshotService-->>PrepareUpdateCommand: return snapshot details
  PrepareUpdateCommand-->>Operator: report preparation status

Loading

sequenceDiagram
  participant Operator
  participant FinishUpdateCommand
  participant RunHealthChecksCommand
  participant UpdateSnapshotService
  Operator->>FinishUpdateCommand: finish update
  FinishUpdateCommand->>RunHealthChecksCommand: run health checks
  RunHealthChecksCommand-->>FinishUpdateCommand: return health result
  FinishUpdateCommand->>UpdateSnapshotService: resolve snapshot on failure
  UpdateSnapshotService-->>FinishUpdateCommand: return rollback guide
  FinishUpdateCommand-->>Operator: report healthy or unhealthy status

Loading

Merge Risk: ⚪ Minimal · up to d4a5f

The PR adds guarded update snapshots, compatibility checks, retention, health checks, and rollback guidance; no actionable merge-blocking risk remains beyond normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main changes: protected update snapshots and rollback guidance.
Description check	✅ Passed	The description directly explains the snapshot safety, Composer compatibility checks, retention, rollback guidance, validation, and test results covered by the changeset.
Docstring Coverage	✅ Passed	Docstring coverage is 95.45% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 8 files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

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