Harden fresh-install empty state and API fallback handling

Author: alexphillips-dev

archive/folderview.plus-2026.03.08.05.txz

@@ -0,0 +1 @@
+1e59e3efe1562eb99d5595657dc9a39caf08d46d377cb0f03fea6f8e3ab00fe2  folderview.plus-2026.03.08.05.txz

archive/folderview.plus-2026.03.08.05.txz.sha256

@@ -6,13 +6,20 @@
 <!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.08.04">
-<!ENTITY md5 "2e71f08fbeb23ce32587c25abd680b71">
+<!ENTITY version "2026.03.08.05">
+<!ENTITY md5 "0a80435be4ea2e2e2b4a03c3ebf1d8da">
 ]>
 
 <PLUGIN name="&name;" author="&author;" version="&version;" launch="&launch;" pluginURL="&pluginURL;" icon="folder-icon.png" support="https://github.com/alexphillips-dev/FolderView-Plus/issues" min="7.0.0">
     <CHANGES>
 
+###2026.03.08.05
+- Bug fix: hardened first-install behavior when no prior folder JSON data exists.
+- Reliability: sanitize error-shaped API responses before rendering folder/state tables.
+- UX: improved empty-state messages for fresh installs and hide-empty-folder scenarios.
+- Regression guard: added tests for first-run API fallback and empty-state handling.
+
+
 ###2026.03.08.04
 - Bug fix: resolved a first-install regression that could render the Settings page blank.
 - Reliability: added startup safeguards so basic Docker/VM sections stay visible even if initial API calls fail.

folderview.plus.plg

@@ -4600,8 +4600,35 @@ const maybeShowUpdateNotesPanel = async () => {
     });
 };
 
-const fetchFolders = async (type) => apiGetJson(`/plugins/folderview.plus/server/read.php?type=${type}`);
-const fetchTypeInfo = async (type) => apiGetJson(`/plugins/folderview.plus/server/read_info.php?type=${type}`);
+const sanitizeTypeMapResponse = (response) => {
+    if (!response || typeof response !== 'object' || Array.isArray(response)) {
+        return {};
+    }
+    if (response.ok === false && typeof response.error === 'string') {
+        return {};
+    }
+    return response;
+};
+
+const sanitizeTypeInfoMap = (value) => {
+    const source = sanitizeTypeMapResponse(value);
+    const output = {};
+    for (const [name, item] of Object.entries(source)) {
+        if (typeof name !== 'string' || !name.trim()) {
+            continue;
+        }
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            continue;
+        }
+        output[name] = item;
+    }
+    return output;
+};
+
+const fetchFolders = async (type) => (
+    utils.normalizeFolderMap(sanitizeTypeMapResponse(await apiGetJson(`/plugins/folderview.plus/server/read.php?type=${type}`)))
+);
+const fetchTypeInfo = async (type) => sanitizeTypeInfoMap(await apiGetJson(`/plugins/folderview.plus/server/read_info.php?type=${type}`));
 
 const fetchBackups = async (type) => {
     const resolvedType = normalizeManagedType(type);
@@ -5628,6 +5655,7 @@ const offerUndoAction = async (type, backup, actionLabel) => {
 const buildRowsHtml = (type, folders, memberSnapshot = {}, hideEmptyFolders = false, healthMetrics = null, statusContext = null) => {
     const isDockerType = type === 'docker';
     const TABLE_COLUMN_COUNT = 10;
+    const folderCount = Object.keys(folders || {}).length;
     const dockerHealthPrefs = isDockerType ? normalizeHealthPrefs('docker') : null;
     const statusPrefs = normalizeStatusPrefs(type);
     const rows = [];
@@ -5945,6 +5973,15 @@ const buildRowsHtml = (type, folders, memberSnapshot = {}, hideEmptyFolders = fa
         const clearButton = showClearFilters
             ? `<button type="button" class="folder-empty-clear-filter" onclick="clearFolderTableFilters('${type}')">Clear filters</button>`
             : '';
+        if (folderCount <= 0 && !showClearFilters) {
+            const firstRunMessage = isDockerType
+                ? 'No Docker folders yet. Create your first folder in the Docker tab or import an export file.'
+                : 'No VM folders yet. Create your first folder in the VMs tab or import an export file.';
+            return `<tr><td colspan="${TABLE_COLUMN_COUNT}" class="folder-empty-cell">${firstRunMessage}</td></tr>`;
+        }
+        if (folderCount > 0 && hideEmptyFolders && !showClearFilters) {
+            return `<tr><td colspan="${TABLE_COLUMN_COUNT}" class="folder-empty-cell">All folders are currently hidden by "Hide empty folders".</td></tr>`;
+        }
         return `<tr><td colspan="${TABLE_COLUMN_COUNT}" class="folder-empty-cell">No folders match current filters${filterSuffix}. ${clearButton}</td></tr>`;
     }
     return rows.join('');

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

@@ -88,3 +88,14 @@ test('fresh install guard keeps basic Docker/VM sections visible on startup fail
     assert.match(script, /visibleKeys\.add\(section\.key\);/);
     assert.match(script, /showError\('Initial data load failed', error\);/);
 });
+
+test('fresh install fallback sanitizes error-shaped API payloads and shows empty-state guidance', () => {
+    assert.match(script, /const sanitizeTypeMapResponse = \(response\) =>/);
+    assert.match(script, /if \(response\.ok === false && typeof response\.error === 'string'\) \{/);
+    assert.match(script, /const sanitizeTypeInfoMap = \(value\) =>/);
+    assert.match(script, /const fetchFolders = async \(type\) =>/);
+    assert.match(script, /const fetchTypeInfo = async \(type\) =>/);
+    assert.match(script, /No Docker folders yet\./);
+    assert.match(script, /No VM folders yet\./);
+    assert.match(script, /All folders are currently hidden by "Hide empty folders"\./);
+});