fix(admin): polish backup recovery UI and health separation

Author: itsshashanksp

admin/assets/admin.css

@@ -572,6 +572,8 @@ tr:last-child td {
 .backup-summary {
   display: grid;
   min-width: 0;
+  min-height: 92px;
+  align-content: start;
   gap: 7px;
   padding: 15px;
   border: 1px solid var(--line);
@@ -626,6 +628,25 @@ tr:last-child td {
   overflow-y: hidden;
   overscroll-behavior-inline: contain;
 }
+.recovery-points-scroll {
+  --recovery-visible-rows: 10;
+  --recovery-row-block-size: 3.75rem;
+  max-height: calc(var(--recovery-row-block-size) * (var(--recovery-visible-rows) + 1));
+  overflow: auto;
+  overscroll-behavior: contain;
+  scrollbar-gutter: stable;
+}
+.recovery-points-scroll:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+.recovery-points-scroll thead th {
+  position: sticky;
+  z-index: 1;
+  top: 0;
+  background: var(--surface);
+  box-shadow: 0 1px 0 var(--line);
+}
 .backup-table th:nth-child(1) { width: 31%; }
 .backup-table th:nth-child(2) { width: 23%; }
 .backup-table th:nth-child(3) { width: 15%; }
@@ -654,6 +675,18 @@ tr:last-child td {
   background: #fff1d7;
   color: var(--warning);
 }
+.badge.change-added {
+  background: var(--accent-soft);
+  color: #176b59;
+}
+.badge.change-modified {
+  background: #fff1d7;
+  color: var(--warning);
+}
+.badge.change-deleted {
+  background: #fdf0ef;
+  color: #842d26;
+}
 .restore-file-row {
   display: grid;
   grid-template-columns: auto minmax(0, 1fr) auto;
@@ -748,6 +781,41 @@ dialog.backup-dialog {
 .backup-dialog__surface {
   max-height: calc(100dvh - 32px);
 }
+.backup-change-section {
+  display: grid;
+  min-width: 0;
+  gap: 9px;
+}
+.backup-change-section h3 {
+  margin: 0;
+  font-size: 14px;
+}
+.backup-change-list {
+  display: grid;
+  max-height: min(15rem, 32vh);
+  margin: 0;
+  padding: 0;
+  overflow-y: auto;
+  border: 1px solid var(--line);
+  border-radius: 9px;
+  list-style: none;
+  overscroll-behavior: contain;
+}
+.backup-change-list li {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  align-items: center;
+  gap: 10px;
+  padding: 10px 12px;
+}
+.backup-change-list li + li {
+  border-top: 1px solid var(--line);
+}
+.backup-change-list code {
+  min-width: 0;
+  overflow-wrap: anywhere;
+  color: var(--ink);
+}
 .dialog-detail-list {
   display: grid;
   grid-template-columns: minmax(130px, 190px) minmax(0, 1fr);
@@ -829,6 +897,14 @@ dialog.backup-dialog {
   color: var(--muted);
   text-align: center;
 }
+.empty strong,
+.empty span {
+  display: block;
+}
+.empty strong {
+  margin-bottom: 6px;
+  color: var(--ink);
+}
 
 .pre-auth {
   background: radial-gradient(circle at top, #e6f4f1 0, var(--canvas) 42%);

admin/assets/admin.js

@@ -121,17 +121,25 @@ public function preview(string $archivePath): array
         $manifest = $this->verifyArchive($archivePath, true);
         $changed = [];
         $unchanged = [];
+        $changes = [];
         foreach ($manifest['files'] as $file) {
             $logical = $file['path'];
             $current = $this->loadAndValidateSource($logical, $this->sources[$logical], true);
             $same = hash_equals(hash('sha256', $this->encodeJson($current)), $file['sha256']);
-            if ($same) $unchanged[] = $logical; else $changed[] = $logical;
+            if ($same) {
+                $unchanged[] = $logical;
+            } else {
+                $changed[] = $logical;
+                $changes[] = ['path' => $logical, 'type' => 'modified'];
+            }
         }
         return [
             'recoveryPointId' => $manifest['recoveryPointId'], 'createdAt' => $manifest['createdAt'],
             'applicationVersion' => $manifest['application']['version'], 'formatVersion' => $manifest['formatVersion'],
             'trigger' => $manifest['trigger'] ?? 'legacy', 'createdBy' => $manifest['createdBy'] ?? null,
-            'files' => array_column($manifest['files'], 'path'), 'changedFiles' => $changed, 'unchangedFiles' => $unchanged,
+            'files' => array_column($manifest['files'], 'path'), 'configurationFiles' => count($manifest['files']),
+            'changedFiles' => $changed, 'filesChanging' => count($changes), 'changes' => $changes,
+            'unchangedFiles' => $unchanged,
             'schemaCompatible' => true, 'encryptionKeyAvailable' => true,
             'verification' => 'valid', 'authenticity' => 'valid', 'warnings' => [],
         ];

app/Backup/ApplicationBackupManager.php

@@ -18,7 +18,6 @@ final class ApplicationHealthMonitor
     private string $runtimeDirectory;
     private string $logDirectory;
     private string $sessionDirectory;
-    private ?string $backupDirectory;
     private string $databaseCachePath;
     private int $databaseCacheTtl;
     private int $diskWarningBytes;
@@ -40,9 +39,6 @@ public function __construct(array $options = [])
             $savePath = (string)end($parts);
         }
         $this->sessionDirectory = $savePath !== '' ? $savePath : sys_get_temp_dir();
-        $configuredBackup = $options['backupDirectory'] ?? getenv('GENERIC_BACKUP_DIR');
-        $this->backupDirectory = is_string($configuredBackup) && trim($configuredBackup) !== ''
-            ? rtrim(trim($configuredBackup), '/\\') : null;
         $this->databaseCachePath = $options['databaseCachePath']
             ?? $this->runtimeDirectory . '/health/database-health.json';
         $this->databaseCacheTtl = max(1, (int)($options['databaseCacheTtl'] ?? 15));
@@ -94,7 +90,6 @@ public function detailed(array $processes): array
             'logging' => $this->loggingHealth(),
             'sessions' => $this->sessionHealth(),
             'encryption' => $this->encryptionHealth(),
-            'backup' => $this->backupHealth(),
             'processes' => ['status' => $this->processAggregate($processes), 'services' => $processes],
         ];
         $statuses = array_column($checks, 'status');
@@ -279,14 +274,6 @@ private function sessionHealth(): array
             ? 'operational' : 'unavailable'];
     }
 
-    private function backupHealth(): array
-    {
-        if ($this->backupDirectory === null) return ['status' => 'degraded', 'category' => 'not_configured'];
-        $check = $this->directoryHealth($this->backupDirectory, true);
-        return ['status' => $check['status'] === 'healthy' ? 'healthy' : 'degraded',
-            'category' => $check['status'] === 'healthy' ? 'capable' : 'unavailable'];
-    }
-
     private function directoryHealth(string $path, bool $writable): array
     {
         if (!is_dir($path)) return ['status' => 'unhealthy', 'category' => 'missing'];

app/Health/ApplicationHealthMonitor.php

@@ -30,8 +30,9 @@ Readiness validates the supported runtime configuration file set and versions,
 the writable runtime directory, the explicit database availability gate, and
 the ability to decrypt and validate database configuration. It deliberately
 does not open SQL connections. SQL Parser state is independent and cannot make
-the API unready. Logging and backup capability are diagnostic/degraded states,
-not readiness blockers.
+the API unready. Logging capability is a diagnostic/degraded state, not a
+readiness blocker. Backup scheduling and recovery-point status are reported
+only on Admin → Backup & Recovery and do not affect System Health.
 
 The database readiness categories are `database_available`,
 `database_disconnected`, `configuration_missing`, `configuration_invalid`, and
@@ -55,8 +56,6 @@ safe checks for:
 - fail-open logging capability;
 - PHP session-directory availability;
 - encryption-key presence and usability, without exposing key material;
-- optional `GENERIC_BACKUP_DIR` capability, without creating or verifying a
-  backup;
 - Admin/API/SQL Parser running, stopped, stale, crashed, or unresponsive state
   as determined by the existing process managers.
 
@@ -70,14 +69,15 @@ Server connection load.
 
 Directory checks are shallow: exists/readable/writable plus `disk_free_space`.
 They do not traverse files. Default warning and critical free-space thresholds
-are 1 GiB and 256 MiB; these classify diagnostics only. A missing logging or
-backup directory is degraded because audit logging is intentionally fail-open
-and backup execution is not part of request serving. A required runtime,
-configuration, session, or database dependency can be unhealthy.
-
-`GENERIC_BACKUP_DIR` means only that an operator-designated backup destination
-is configured and writable. It does not prove that a recent or verified backup
-exists. Backup verification remains an explicit operator operation.
+are 1 GiB and 256 MiB; these classify diagnostics only. A missing logging
+directory is degraded because audit logging is intentionally fail-open. A
+required runtime, configuration, session, or database dependency can be
+unhealthy.
+
+Removing backup scheduling from System Health does not affect restore safety.
+Every activation still runs `ApplicationHealthMonitor::restoreSafety()` after
+staging and validation; a failure triggers rollback to the previous
+configuration.
 
 ## Hosting layers
 

docs/Monitoring-and-Health.md

@@ -178,7 +178,9 @@ function backupCreateLegacyV2(string $source, string $target, string $encodedSig
     backupFailure(fn () => SafeZipArchive::create($backupParent . '/duplicate-too-large.zip', ['large.bin' => str_repeat('x', SafeZipArchive::MAX_ENTRY_BYTES + 1)]), 'Oversized ZIP entry was accepted.');
 
     $preview = $manager->preview($bundlePath);
-    backupAssert($preview['verification'] === 'valid' && $preview['authenticity'] === 'valid' && $preview['changedFiles'] === [], 'Restore preview is invalid.');
+    backupAssert($preview['verification'] === 'valid' && $preview['authenticity'] === 'valid'
+        && $preview['configurationFiles'] === 6 && $preview['filesChanging'] === 0
+        && $preview['changedFiles'] === [] && $preview['changes'] === [], 'Restore preview is invalid.');
     $restorePath = $backupParent . '/restore-stage';
     $restore = $manager->stageRestore($bundlePath, $restorePath);
     backupAssert($restore['ready'] && $restore['files'] === 6 && is_file($restorePath . '/signature.json'), 'ZIP restore staging failed.');
@@ -187,7 +189,14 @@ function backupCreateLegacyV2(string $source, string $target, string $encodedSig
     $changedAdmin = AdminConfigurationRepository::defaults();
     $changedAdmin['server']['adminPort'] = 8099;
     backupWriteFixture($runtimePath . '/admin.json', $changedAdmin);
-    backupAssert(in_array('config/admin.json', $manager->preview($bundlePath)['changedFiles'], true), 'Preview did not report changed configuration.');
+    $changedPreview = $manager->preview($bundlePath);
+    backupAssert($changedPreview['filesChanging'] === 1
+        && $changedPreview['changedFiles'] === ['config/admin.json']
+        && $changedPreview['changes'] === [['path' => 'config/admin.json', 'type' => 'modified']], 'Preview did not report exact changed configuration metadata.');
+    $previewMetadata = json_encode($changedPreview['changes'], JSON_THROW_ON_ERROR);
+    foreach (['fake-user-password', 'fake-api-secret', 'fake-database-password', $key, $signingContents] as $secret) {
+        backupAssert(!str_contains($previewMetadata, $secret), 'Restore preview change metadata exposed secret material.');
+    }
     $activated = $manager->activateRestore($bundlePath, static fn (): bool => true);
     backupAssert($activated['restored'] && JsonFileStore::load($runtimePath . '/admin.json')['server']['adminPort'] !== 8099, 'Atomic restore activation failed.');
     $changedAdmin['server']['adminPort'] = 8098;

tests/BackupRecoveryTest.php

@@ -83,7 +83,9 @@ function healthRemove(string $path): void
         'sqlParser' => ['running' => false, 'healthy' => false, 'status' => 'stopped', 'pid' => null, 'port' => null],
     ];
     $detail = $monitor->detailed($processes);
-    healthAssert(isset($detail['status'], $detail['checks']['database'], $detail['checks']['filesystem']) && $tests === 1, 'Detailed health schema or database test is invalid.');
+    healthAssert(isset($detail['status'], $detail['checks']['database'], $detail['checks']['filesystem'])
+        && !isset($detail['checks']['backup']) && $detail['status'] === 'healthy'
+        && $tests === 1, 'Detailed health schema, aggregation, or database test is invalid.');
     $monitor->detailed($processes);
     healthAssert($tests === 1, 'Database health cache did not prevent repeated expensive connectivity work.');
     $serialized = json_encode($detail, JSON_THROW_ON_ERROR);
@@ -129,12 +131,14 @@ function healthRemove(string $path): void
     $lowDisk = new ApplicationHealthMonitor([
         'configurationDirectory' => $configuration, 'databasePath' => $database,
         'runtimeDirectory' => $runtime, 'logDirectory' => $logs, 'sessionDirectory' => $sessions,
-        'backupDirectory' => $backups, 'databaseAvailable' => static fn (): bool => true,
+        'databaseAvailable' => static fn (): bool => true,
         'diskWarningBytes' => 100, 'diskCriticalBytes' => 10, 'diskSpace' => static fn (): int => 50,
     ]);
     healthAssert($lowDisk->detailed($processes)['checks']['filesystem']['status'] === 'degraded', 'Low disk space was not classified as warning.');
     @rmdir($backups);
-    healthAssert($monitor->detailed($processes)['checks']['backup']['category'] === 'unavailable', 'Backup directory capability failure was not detected.');
+    $withoutBackupDirectory = $monitor->detailed($processes);
+    healthAssert(!isset($withoutBackupDirectory['checks']['backup'])
+        && $withoutBackupDirectory['status'] === 'healthy', 'Backup availability still affects System Health.');
 
     $authFailure = new ApplicationHealthMonitor([
         'configurationDirectory' => $configuration, 'databasePath' => $database,

tests/HealthMonitoringTest.php

@@ -393,9 +393,25 @@ function (array $database) use (&$connectionTests, &$testedDatabase): void {
         && !str_contains($adminJavaScript, 'webkitdirectory'),
         'Admin Backup & Recovery does not use native ZIP selection/download with explicit confirmation.');
     foreach (['.backup-summary-grid', '.backup-schedule-grid', '.backup-table-wrap', '.recovery-point-id',
-        '.restore-file-row', 'dialog.backup-dialog'] as $backupStyle) {
+        '.recovery-points-scroll', '.backup-change-list', '.restore-file-row', 'dialog.backup-dialog'] as $backupStyle) {
         unifiedAdminAssert(str_contains($adminCss, $backupStyle), "Backup & Recovery CSS is missing {$backupStyle}.");
     }
+    unifiedAdminAssert(str_contains($adminJavaScript, 'No Recovery Points')
+        && str_contains($adminJavaScript, 'No verified application recovery points are currently available.')
+        && str_contains($adminJavaScript, 'tabindex="0" aria-label="Recovery points"')
+        && str_contains($adminCss, '--recovery-visible-rows: 10')
+        && str_contains($adminCss, 'position: sticky'), 'Recovery points do not provide a bounded, accessible scrolling table or empty state.');
+    foreach (['No configuration changes detected.', '["added", "modified", "deleted"]', 'backupChangeList(changes)',
+        'preview.configurationFiles', 'preview.filesChanging', 'preview.changes'] as $previewUi) {
+        unifiedAdminAssert(str_contains($adminJavaScript, $previewUi), "Restore preview is missing {$previewUi} support.");
+    }
+    unifiedAdminAssert(strpos($adminJavaScript, 'doneValidating();') < strpos($adminJavaScript, 'if (!preview) return;'),
+        'Restore preview validation state is not cleared before the preview dialog opens.');
+    unifiedAdminAssert(!str_contains($adminJavaScript, '"encryption",\n      "backup",')
+        && !str_contains((string)file_get_contents(__DIR__ . '/../app/Health/ApplicationHealthMonitor.php'), "'backup' => \$this->backupHealth()"),
+        'Backup remains in the System Health response or UI aggregation.');
+    unifiedAdminAssert(str_contains((string)file_get_contents(__DIR__ . '/../app/Health/ApplicationHealthMonitor.php'), 'public function restoreSafety(): array'),
+        'Restore safety health validation was removed while separating Backup from System Health.');
     unifiedAdminAssert(!str_contains(strtolower($adminJavaScript), 'test saved configuration'), 'Removed saved database test remains in the Admin Console.');
     unifiedAdminAssert(!str_contains($adminJavaScript, 'Runtime access'), 'Database runtime lifecycle remains under Configuration.');
     unifiedAdminAssert(str_contains($adminJavaScript, 'data-database-runtime'), 'Database runtime lifecycle is missing from System Health.');