fix: report ebook welcome creation failures

Author: DevanMetz

.github/workflows/release.yml

@@ -276,6 +276,7 @@ jobs:
             build/ebook-library/source.json
             build/ebook-library/ebook_library.inc
             build/ebook-library/ebook_library_config.inc
+            build/ebook-library/storage_source.inc
           if-no-files-found: warn
           retention-days: 14
 

ROADMAP.md

@@ -62,6 +62,7 @@ Phase 1 software progress is also underway:
 
 - [x] Scope and I2C capture cleanup no longer retries publication after a rejected write or failed I2C flush/sync. I2C releases recording ownership on known SD failure; both writers preserve the first cause through close and report once. All 35 original native writer/storage cases pass; the callbacks preceding the writer fix fail 16 controls. Exact CSV/TMP bytes, Scope filename collision, pre-flush timing and 25 independent failure/success cycles per writer are checked with closed handles. UI, data, time, mount and fault boundaries are controlled; ADC/drivers and physical SD/panel remain separate gates. Linux CI retains source hashes and logs.
 - [x] Ebook library listings confirm regular-file metadata before accepting `.txt` entries and report directory setup/open/read/stat/close errors, entry capacity and skipped long paths. Failed listings no longer claim an empty library; the first failure survives close. All 28 native existing-directory/file cases pass, including unchanged bytes, callback path ownership, first-error checks and 25 reopen cycles with closed handles. The previous callback fails 18 controls. UI, timer, mount, download and error boundaries are controlled; welcome creation and physical SD/panel checks remain separate. Linux CI retains source hashes and logs.
+- [x] First-run ebook welcome creation checks fresh open/write errors and stream flags, preserves the first cause through cleanup, and shows a creation warning without an empty-library hint. All 55 native library cases pass: 28 existing listing controls plus 27 welcome controls; the preceding callback fails 25 welcome controls. Exact final/TMP bytes, retained collisions, commit faults and 25 failure/recreation/reopen cycles are checked with closed file/directory handles. Existing directories do not retry or rewrite the welcome file. UI, timer, mount and faults are controlled; physical SD/panel and power cuts remain open. CI retains the complete compiled storage helper and source hashes.
 - [x] UART/RS-485 logging retries only filename collisions, reports the first preparation/write/sync failure, and retains rejected headers as unpublished TMPs. All 82 native start/write/Stop and storage cases pass; the previous functions fail 42 controls. Exact bytes, ten-name limits, tick wrap and 25 failure/restart pairs per link are checked with unchanged retained TMPs and closed handles. UI, clock, mount and faults are controlled; drivers and physical SD/panel remain separate checks. Linux CI retains source hashes and logs.
 - [x] Scope and I2C capture constructors stop on preparation/stream-creation failures and preserve fresh first errors through cleanup. The capture suite now passes 78 native cases: 35 writer cases plus 43 constructor cases; the previous constructors fail 14 controls. Both 100-name limits, existing bytes, empty/partial TMP recovery and 25 header-failure/restart pairs per constructor are checked with closed handles and guarded I2C watch ownership. Paths, UI, clocks, data and faults are controlled; physical SD/panel and drivers remain separate checks.
 - [x] System reports the firmware/commit, reset reason, uptime, panel, heap, storage capacity, current OTA state, and persistent last OTA result.

docs/architecture.md

@@ -107,7 +107,7 @@ Files dispatches supported CSVs to those viewers before its text fallback. The f
 
 Files directory browsing resets errno before each directory read so per-entry `stat` errors cannot masquerade as an enumeration error at EOF. A failed read or close keeps the visited entries visible with an explicit incomplete-list warning, preserving the first error. Entry capacity and skipped long paths are disclosed. The existing 64 path slots include a parent-navigation slot when needed, and each path remains bounded to 256 bytes. SD root and descendant errors reach the shared callback. Native directory/file checks verify these transitions and callback path ownership; UI, mount paths and error injection are controlled.
 
-The ebook library verifies regular-file metadata before offering a `.txt` entry, excluding matching directories and unconfirmed paths. Directory setup/open failures show their cause; read/stat/close failures keep confirmed rows visible with an incomplete-list warning. Fresh errno checks preserve the first failure, and failed or skipped listings cannot claim the library is empty. The existing 64-entry and 256-byte path bounds are disclosed. Native checks use an existing BOOKS directory with controlled UI, timer, SD, download and fault boundaries; welcome creation and physical storage remain separate checks.
+The ebook library verifies regular-file metadata before offering a `.txt` entry, excluding matching directories and unconfirmed paths. Directory setup/open failures show their cause; read/stat/close failures keep confirmed rows visible with an incomplete-list warning. A newly created directory writes its welcome file with fresh errno and stream checks, preserving the first failure through cleanup. Failed welcome creation shows its cause without an empty-library hint; confirmed entries remain available. Healthy creation uses the existing new-file commit helper, while an existing directory never rewrites the welcome file. Failed or skipped listings cannot claim the library is empty. The existing 64-entry and 256-byte path bounds are disclosed. Native checks cover directory listing and welcome bytes with controlled UI, timer, SD, download and fault boundaries; physical storage remains a separate check.
 
 Default ebook downloads keep the file pointer and first write error in a per-download stack context passed to the HTTP callback. The pinned SDK body parser ignores callback return codes, so this context stops later file writes and gates publication independently of the client result. Fresh errno at probe/preparation/write/close boundaries prevents stale causes; close/removal cannot overwrite a captured write error. Confirmed 2xx downloads still use the existing new-file commit helper. Callback state lives until SDK cleanup finishes, then file ownership is closed or consumed by storage. Native file tests control HTTP events and faults; the unflashed build checks the actual SDK interface. Worker/timer scheduling, Wi-Fi/TLS, physical SD and panel behavior remain separate checks.
 

docs/data-formats.md

@@ -39,7 +39,7 @@ Directory browsing uses 64 stored path slots of 256 bytes each, including a pare
 
 Choose a record from the current page and tap **COPY ROW** to put its original 1-128 bytes on the shared RAM clipboard. The selector and timeline use the same record numbers: positions among loaded valid rows, not physical CSV line numbers. Page/filter changes select the first matching record on the new page; changing Hex/ASCII preserves the selection. Rows of 129-256 bytes remain viewable but cannot be partially copied. Empty filters and failed copies preserve the clipboard. Record bytes can then be pasted into Byte Lab or RTU Frames; a logged RX/TX chunk may split or combine protocol frames, so a record is not a guarantee of a complete message. Copy changes neither the CSV nor the displayed byte values.
 
-The ebook library accepts case-insensitive `.txt` names only after confirming regular-file metadata, and skips directories or entries with failed metadata. It stores at most 64 paths of 256 bytes, disclosing filled slots and overlong names. Setup/open errors show their cause; read/stat/close errors mark retained confirmed entries incomplete and reach the SD callback with the first failure. The copy-books hint appears only after an error-free listing with no accepted or overlong entries. Native existing-directory checks cover these transitions with controlled UI, timer, mount and error boundaries; welcome creation and physical SD/panel behavior remain separate checks.
+The ebook library accepts case-insensitive `.txt` names only after confirming regular-file metadata, and skips directories or entries with failed metadata. It stores at most 64 paths of 256 bytes, disclosing filled slots and overlong names. Setup/open errors show their cause; read/stat/close errors mark retained confirmed entries incomplete and reach the SD callback with the first failure. A newly created BOOKS directory receives the unchanged welcome text through `WELCOME.TMP` and the new-file sync/close/publication helper. Open/write/commit errors show a welcome-creation warning; missing errno becomes EIO, and cleanup preserves the first write failure. Rejected or stream-flagged writes discard the TMP when removal succeeds; failed removal or commit retains unpublished bytes. An existing final is preserved. Reopening an existing directory does not rewrite or retry the welcome file. The copy-books hint appears only after an error-free listing and welcome creation with no accepted or overlong entries. Native directory/file checks cover these transitions with controlled UI, timer, mount and error boundaries; physical SD/panel and power-loss behavior remain separate checks.
 
 Default ebook downloads stop before opening a writer when the installation probe or old-TMP removal fails. Each write checks its own errno and stream flag, using EIO when a failure supplies no cause. The first failed chunk stops later file writes and prevents publication even if the HTTP client later reports success. A failed download attempts to close/remove its TMP and preserves the first storage error through cleanup; failed removal can retain partial bytes. Healthy 2xx downloads use the existing new-file sync/close/publication helper, which retains an unpublished TMP on commit failure and never overwrites an existing final. Native file checks use controlled HTTP events and faults; physical SD/TLS and power-loss behavior remain open.
 

docs/testing.md

@@ -202,11 +202,13 @@ Reader initialization is retained and checked as source, including zero offsets
 python tools/test_ebook_library.py --compiler 'C:/path/to/clang.exe'
 ```
 
-The portable runner compiles the actual `show_ebooks`, `ebook_supported` and `browser_prefix` functions. Its 28 cases check an existing native BOOKS directory: empty/unsupported contents, case-insensitive extensions, `.txt` directory exclusion, entry/path limits, SD availability, mkdir/open/read/stat/close failures, missing/stale errno, first-error preservation, callback path ownership, download-status messages, reopening and 25 success/error/success cycles. The previous callback fails 18 controls. Every case verifies unchanged staged file bytes and closed native directory handles; cleanup leaves no modeled timers.
+The portable runner compiles the actual `show_ebooks`, `ebook_supported` and `browser_prefix` functions and the complete `storage_io.c`. Its 55 cases include the existing 28 native-directory controls: empty/unsupported contents, case-insensitive extensions, `.txt` directory exclusion, entry/path limits, SD availability, mkdir/open/read/stat/close failures, missing/stale errno, first-error preservation, callback path ownership, download-status messages, reopening and 25 success/error/success cycles. Every listing case verifies unchanged staged file bytes and closed native directory handles; cleanup leaves no modeled timers.
 
-Windows Find APIs and POSIX directory APIs supply the entries; native dot entries are normalized. The overlong name and operation failures are injected. UI, timers, logical mount paths, download helpers and the SD error callback are controlled. Reopen cases restore modeled SD availability and check that a successful listing clears its warning without erasing earlier error reports. The unchanged welcome-writing branch is excluded by using an existing directory and rejecting any welcome I/O. Actual LVGL cleanup, timer ticks, downloads, SDK mounts, SD callback filtering, physical SD/panel, latency and power-loss behavior remain outside this fixture. A null directory read with zero errno remains EOF.
+The additional 27 controls create a new native BOOKS directory and exercise the welcome branch. They check the exact unchanged welcome text, a successful reopen without another write, open/write/flush/sync/close/probe/publication failures, missing errno, positive writes and flushes with a stream error, an existing final, and compounded close/removal errors. Failed creation displays its cause and suppresses the empty-library hint. Rejected writes stop before explicit flush/sync/publication; successful removal discards their TMP, while failed removal preserves its exact partial or full bytes. Commit failures retain the unpublished TMP and any existing final. Twenty-five failure/recreation/reopen cycles close all native file and directory handles. Recreation removes only the fixture's owned flat files and empty directory; reopening an existing directory does not automatically retry welcome creation. The preceding callback fails 25 welcome controls while all 28 listing controls still pass.
 
-The library retains 64 stored paths of 256 bytes. The entry-limit message means those slots filled; no extra read proves that more entries exist. Generated callback/config source, full main/function/test hashes and compile/result logs stay under `build/ebook-library/`. Linux CI retains `ebook-library-logs`, including available failure diagnostics. These 28 checks are separate from the Windows native total.
+Windows Find APIs and POSIX directory APIs supply the entries; native dot entries are normalized. The overlong name and operation failures are injected. UI, timers, logical mount paths, download helpers and the SD error callback are controlled; successful operations deliberately leave stale errno, and failures can supply no new cause. Reopen cases restore modeled SD availability and check that a successful listing clears its warning without erasing earlier error reports. Actual LVGL cleanup, timer ticks, downloads, SDK mounts, SD callback filtering, physical SD/panel, latency and power-loss behavior remain outside this fixture. A null directory read with zero errno remains EOF.
+
+The library retains 64 stored paths of 256 bytes. The entry-limit message means those slots filled; no extra read proves that more entries exist. Generated callback/config/storage source, full main/function/storage/header/test hashes and compile/result logs stay under `build/ebook-library/`. Linux CI retains `ebook-library-logs`, including available failure diagnostics. These 55 checks are separate from the Windows native total.
 
 ## Ebook downloads
 

main/main.c

@@ -4690,21 +4690,34 @@ static void show_ebooks(void)
         lv_list_add_text(list, message);
         return;
     }
+    int welcome_error = 0;
     if (created) {
         const char *temporary = SD_PATH "/BOOKS/WELCOME.TMP";
         const char *final = SD_PATH "/BOOKS/WELCOME.TXT";
+        errno = 0;
         FILE *welcome = fopen(temporary, "wb");
         if (welcome) {
-            if (fputs("Welcome to Tab5 Books!\n\nCopy .txt ebooks into the BOOKS folder on the SD card. Use Next and Prev to move through the book, and Text to change the reading size.\n", welcome) < 0) {
-                int error = errno ? errno : EIO;
+            errno = 0;
+            if (fputs("Welcome to Tab5 Books!\n\nCopy .txt ebooks into the BOOKS folder on the SD card. Use Next and Prev to move through the book, and Text to change the reading size.\n", welcome) < 0 || ferror(welcome)) {
+                welcome_error = errno ? errno : EIO;
+                errno = 0;
                 fclose(welcome);
+                welcome = NULL;
+                errno = 0;
                 remove(temporary);
-                sd_record_error(error);
-            } else if (storage_commit_new_file(&welcome, temporary, final) != 0) {
-                sd_record_error(errno ? errno : EIO);
+            } else {
+                errno = 0;
+                if (storage_commit_new_file(&welcome, temporary, final) != 0)
+                    welcome_error = errno ? errno : EIO;
             }
         } else {
-            sd_record_error(errno ? errno : EIO);
+            welcome_error = errno ? errno : EIO;
+        }
+        if (welcome_error) {
+            sd_record_error(welcome_error);
+            char message[96];
+            snprintf(message, sizeof(message), "Could not create WELCOME.TXT: %s", strerror(welcome_error));
+            lv_list_add_text(list, message);
         }
     }
     errno = 0;
@@ -4767,7 +4780,7 @@ static void show_ebooks(void)
         snprintf(message, sizeof(message), "Skipped %u book paths that exceed the path limit", (unsigned)skipped);
         lv_list_add_text(list, message);
     }
-    if (!file_path_count && !error && !skipped) lv_list_add_text(list, "Copy .txt books into /sdcard/BOOKS");
+    if (!file_path_count && !error && !skipped && !welcome_error) lv_list_add_text(list, "Copy .txt books into /sdcard/BOOKS");
     if (ebook_download_busy) {
         lv_list_add_text(list, "Downloading free classics...");
     } else if (ebook_defaults_missing()) {