feat: diagnostics v2 with integrity, state snapshots, history, and privacy modes

Author: alexphillips-dev

archive/folderview.plus-2026.03.06.3.txz

@@ -6,13 +6,24 @@
 <!ENTITY launch "Settings/FolderViewPlus">
 <!ENTITY plugdir "/usr/local/emhttp/plugins/&name;">
 <!ENTITY pluginURL "https://raw.githubusercontent.com/&github;/main/folderview.plus.plg">
-<!ENTITY version "2026.03.06.2">
-<!ENTITY md5 "e46f08d7df86526c083f2b4a5fe97452">
+<!ENTITY version "2026.03.06.3">
+<!ENTITY md5 "39ac8cf761703bbef75674f8105c8814">
 ]>
 
 <PLUGIN name="&name;" author="&author;" version="&version;" launch="&launch;" pluginURL="&pluginURL;" icon="folder-open-o" support="https://github.com/alexphillips-dev/FolderView-Plus/issues" min="7.0.0">
     <CHANGES>
 
+###2026.03.06.3
+- Expand diagnostics export to schema v2 with richer bug-fixing data:
+  - `integrityChecks` per type (duplicate names/assignments, orphaned members, invalid regex/rules, manual-order gaps),
+  - `stateSnapshot` per folder (computed started/paused/stopped totals, effective status text, badge visibility, status colors),
+  - `environment` block (Unraid/PHP/server/request context),
+  - key file SHA-256 hashes for folder/prefs JSON files.
+- Add diagnostics history tracking (`importExportHistory`) with persistent event log for import/export/clear/reorder/backup actions.
+- Add diagnostics privacy modes:
+  - default `sanitized` export (redacted paths and request-identifying details),
+  - optional `full` export from the UI for deep support cases.
+
 ###2026.03.06.2
 - Fix folder editor alignment for the status color controls so they line up with the rest of the settings form.
 

folderview.plus.plg

@@ -106,26 +106,48 @@ const bulkAssign = async (type, folderId, items) => {
     return response.result;
 };
 
-const getDiagnostics = async () => {
-    const response = await apiGetJson('/plugins/folderview.plus/server/diagnostics.php?action=report');
+const getDiagnostics = async (privacy = 'sanitized') => {
+    const response = await apiGetJson(`/plugins/folderview.plus/server/diagnostics.php?action=report&privacy=${encodeURIComponent(privacy || 'sanitized')}`);
     if (!response.ok) {
         throw new Error(response.error || 'Diagnostics failed.');
     }
     return response.diagnostics || {};
 };
 
-const runDiagnosticAction = async (action, type) => {
+const runDiagnosticAction = async (action, type, privacy = 'sanitized') => {
     const payload = { action };
     if (type) {
         payload.type = type;
     }
+    payload.privacy = privacy || 'sanitized';
     const response = parseJsonResponse(await $.post('/plugins/folderview.plus/server/diagnostics.php', payload).promise());
     if (!response.ok) {
         throw new Error(response.error || 'Diagnostics action failed.');
     }
     return response.diagnostics || {};
 };
 
+const trackDiagnosticsEvent = async ({ eventType, type = null, status = 'ok', source = 'ui', details = {} }) => {
+    if (!eventType) {
+        return;
+    }
+    const payload = {
+        action: 'track_event',
+        eventType: String(eventType),
+        status: String(status || 'ok'),
+        source: String(source || 'ui'),
+        details: JSON.stringify(details || {})
+    };
+    if (type) {
+        payload.type = type;
+    }
+    try {
+        await $.post('/plugins/folderview.plus/server/diagnostics.php', payload).promise();
+    } catch (error) {
+        // Event tracking is best-effort and should never block UI actions.
+    }
+};
+
 const fetchPrefs = async (type) => {
     try {
         const response = await apiGetJson(`/plugins/folderview.plus/server/prefs.php?type=${type}`);
@@ -690,6 +712,15 @@ const downloadType = (type, id) => {
             pluginVersion
         });
         downloadFile(`${folder.name}.json`, toPrettyJson(payload));
+        trackDiagnosticsEvent({
+            eventType: 'export',
+            type,
+            details: {
+                mode: 'single',
+                folderCount: 1,
+                schemaVersion: utils.EXPORT_SCHEMA_VERSION
+            }
+        });
         return;
     }
 
@@ -701,6 +732,15 @@ const downloadType = (type, id) => {
 
     const name = type === 'docker' ? `${EXPORT_BASENAME}.json` : `${EXPORT_BASENAME} VM.json`;
     downloadFile(name, toPrettyJson(payload));
+    trackDiagnosticsEvent({
+        eventType: 'export',
+        type,
+        details: {
+            mode: 'full',
+            folderCount: Object.keys(folders).length,
+            schemaVersion: utils.EXPORT_SCHEMA_VERSION
+        }
+    });
 };
 const importType = async (type) => {
     let selected;
@@ -756,6 +796,16 @@ const importType = async (type) => {
         const backup = await createBackup(type, `before-import-${dialogResult.mode}`);
         await applyImportOperations(type, operations);
         await Promise.all([refreshType(type), refreshBackups(type)]);
+        await trackDiagnosticsEvent({
+            eventType: 'import',
+            type,
+            details: {
+                mode: dialogResult.mode,
+                creates: operations.creates.length,
+                updates: operations.upserts.length,
+                deletes: operations.deletes.length
+            }
+        });
         await offerUndoAction(type, backup, 'Import');
     } catch (error) {
         showError('Import failed', error);
@@ -797,6 +847,14 @@ const clearType = (type, id) => {
             }
 
             await Promise.all([refreshType(type), refreshBackups(type)]);
+            await trackDiagnosticsEvent({
+                eventType: id ? 'delete_folder' : 'clear_folders',
+                type,
+                details: {
+                    deletedCount: id ? 1 : Object.keys(folders).length,
+                    singleFolder: Boolean(id)
+                }
+            });
             await offerUndoAction(type, backup, id ? 'Delete folder' : 'Clear folders');
         } catch (error) {
             showError('Delete failed', error);
@@ -1035,6 +1093,14 @@ const assignSelectedItems = async (type) => {
         const backup = await createBackup(type, 'before-bulk-assign');
         await bulkAssign(type, folderId, selected);
         await Promise.all([refreshType(type), refreshBackups(type)]);
+        await trackDiagnosticsEvent({
+            eventType: 'bulk_assign',
+            type,
+            details: {
+                folderId,
+                itemCount: selected.length
+            }
+        });
         await offerUndoAction(type, backup, 'Bulk assignment');
     } catch (error) {
         showError('Bulk assignment failed', error);
@@ -1171,15 +1237,30 @@ const repairDiagnostics = async (action) => {
 };
 
 const exportDiagnostics = async () => {
-    try {
-        if (!lastDiagnostics) {
-            const diagnostics = await getDiagnostics();
+    swal({
+        title: 'Export diagnostics',
+        text: 'Include full details (paths, names, and request metadata)?\nChoose Cancel for sanitized export.',
+        type: 'warning',
+        showCancelButton: true,
+        confirmButtonText: 'Full export',
+        cancelButtonText: 'Sanitized export'
+    }, async (useFull) => {
+        const privacy = useFull ? 'full' : 'sanitized';
+        try {
+            const diagnostics = await getDiagnostics(privacy);
             renderDiagnostics(diagnostics);
+            downloadFile('FolderView Plus Diagnostics.json', toPrettyJson(diagnostics || {}));
+            await trackDiagnosticsEvent({
+                eventType: 'diagnostics_export',
+                details: {
+                    privacyMode: privacy,
+                    schemaVersion: diagnostics?.schemaVersion || null
+                }
+            });
+        } catch (error) {
+            showError('Diagnostics export failed', error);
         }
-        downloadFile('FolderView Plus Diagnostics.json', toPrettyJson(lastDiagnostics || {}));
-    } catch (error) {
-        showError('Diagnostics export failed', error);
-    }
+    });
 };
 
 const checkForUpdatesNow = async () => {

src/folderview.plus/usr/local/emhttp/plugins/folderview.plus/scripts/folderviewplus.js

@@ -13,6 +13,13 @@
         if (!file_exists($path)) {
             throw new RuntimeException('Backup file not found.');
         }
+        try {
+            appendDiagnosticsHistoryEvent('backup_download', $type, [
+                'name' => basename($path)
+            ], 'ok', 'server');
+        } catch (Throwable $err) {
+            // Non-fatal.
+        }
         header_remove('Content-Type');
         header('Content-Type: application/json');
         header('Content-Disposition: attachment; filename="' . basename($path) . '"');

src/folderview.plus/usr/local/emhttp/plugins/folderview.plus/server/backup.php

@@ -5,11 +5,41 @@
 
 try {
     $action = (string)($_REQUEST['action'] ?? 'report');
+    $privacyMode = normalizeDiagnosticsPrivacyMode((string)($_REQUEST['privacy'] ?? FVPLUS_DIAGNOSTICS_DEFAULT_PRIVACY));
+
+    if ($action === 'track_event') {
+        $eventType = trim((string)($_REQUEST['eventType'] ?? ''));
+        if ($eventType === '') {
+            throw new RuntimeException('Event type is required.');
+        }
+        $type = null;
+        if (isset($_REQUEST['type']) && $_REQUEST['type'] !== '') {
+            $type = ensureType((string)$_REQUEST['type']);
+        }
+        $status = (string)($_REQUEST['status'] ?? 'ok');
+        $source = (string)($_REQUEST['source'] ?? 'ui');
+        $detailsRaw = $_REQUEST['details'] ?? null;
+        $details = [];
+        if (is_string($detailsRaw) && $detailsRaw !== '') {
+            $parsed = json_decode($detailsRaw, true);
+            if (is_array($parsed)) {
+                $details = $parsed;
+            }
+        } elseif (is_array($detailsRaw)) {
+            $details = $detailsRaw;
+        }
+        $event = appendDiagnosticsHistoryEvent($eventType, $type, $details, $status, $source);
+        echo json_encode([
+            'ok' => true,
+            'event' => $event
+        ]);
+        exit;
+    }
 
     if ($action === 'report') {
         echo json_encode([
             'ok' => true,
-            'diagnostics' => getDiagnosticsSnapshot()
+            'diagnostics' => getDiagnosticsSnapshot($privacyMode)
         ]);
         exit;
     }
@@ -19,7 +49,7 @@
         echo json_encode([
             'ok' => true,
             'message' => 'Docker order sync completed.',
-            'diagnostics' => getDiagnosticsSnapshot()
+            'diagnostics' => getDiagnosticsSnapshot($privacyMode)
         ]);
         exit;
     }
@@ -33,7 +63,7 @@
         echo json_encode([
             'ok' => true,
             'message' => 'Preferences normalized and rewritten.',
-            'diagnostics' => getDiagnosticsSnapshot()
+            'diagnostics' => getDiagnosticsSnapshot($privacyMode)
         ]);
         exit;
     }
@@ -44,7 +74,7 @@
         echo json_encode([
             'ok' => true,
             'backup' => $backup,
-            'diagnostics' => getDiagnosticsSnapshot()
+            'diagnostics' => getDiagnosticsSnapshot($privacyMode)
         ]);
         exit;
     }