fix: make file system operations thread-safe (HalFile) (#1212)

## Summary

Fix https://github.com/crosspoint-reader/crosspoint-reader/issues/1137

Introducing `HalFile`, a thin wrapper around `FsFile` that uses a global
mutex to protect file operations.

To test this PR, place the code below somewhere in the code base (I
placed it in `onGoToRecentBooks`)

```cpp
static auto testTask = [](void* param) {
  for (int i = 0; i < 10; i++) {
    String json = Storage.readFile("/.crosspoint/settings.json");
    LOG_DBG("TEST_TASK", "Read settings.json, bytes read: %u", json.length());
  }
  vTaskDelete(nullptr);
};
xTaskCreate(testTask, "test0", 8192, nullptr, 1, nullptr);
xTaskCreate(testTask, "test1", 8192, nullptr, 1, nullptr);
xTaskCreate(testTask, "test2", 8192, nullptr, 1, nullptr);
xTaskCreate(testTask, "test3", 8192, nullptr, 1, nullptr);
delay(1000);
```

It will reliably lead to crash on `master`, but will function correctly
with this PR.

A macro renaming trick is used to avoid changing too many downstream
code files.

---

### AI Usage

While CrossPoint doesn't have restrictions on AI tools in contributing,
please be transparent about their usage as it
helps set the right context for reviewers.

Did you use AI tools to help write this code? **PARTIALLY**, only to
help with tedious copy-paste tasks

---------

Co-authored-by: Zach Nelson <zach@zdnelson.com>

lib/hal/HalStorage.h

@@ -1,10 +1,15 @@
 #pragma once
 
-#include <FS.h>  // need to be included before SdFat.h for compatibility with FS.h's File class
-#include <SDCardManager.h>
+#include <Print.h>
+#include <common/FsApiConstants.h>  // for oflag_t
+#include <freertos/semphr.h>
 
+#include <memory>
+#include <string>
 #include <vector>
 
+class HalFile;
+
 class HalStorage {
  public:
   HalStorage();
@@ -25,31 +30,77 @@ class HalStorage {
   // Ensure a directory exists, creating it if necessary. Returns true on success.
   bool ensureDirectoryExists(const char* path);
 
-  FsFile open(const char* path, const oflag_t oflag = O_RDONLY);
+  HalFile open(const char* path, const oflag_t oflag = O_RDONLY);
   bool mkdir(const char* path, const bool pFlag = true);
   bool exists(const char* path);
   bool remove(const char* path);
   bool rename(const char* oldPath, const char* newPath);
   bool rmdir(const char* path);
 
-  bool openFileForRead(const char* moduleName, const char* path, FsFile& file);
-  bool openFileForRead(const char* moduleName, const std::string& path, FsFile& file);
-  bool openFileForRead(const char* moduleName, const String& path, FsFile& file);
-  bool openFileForWrite(const char* moduleName, const char* path, FsFile& file);
-  bool openFileForWrite(const char* moduleName, const std::string& path, FsFile& file);
-  bool openFileForWrite(const char* moduleName, const String& path, FsFile& file);
+  bool openFileForRead(const char* moduleName, const char* path, HalFile& file);
+  bool openFileForRead(const char* moduleName, const std::string& path, HalFile& file);
+  bool openFileForRead(const char* moduleName, const String& path, HalFile& file);
+  bool openFileForWrite(const char* moduleName, const char* path, HalFile& file);
+  bool openFileForWrite(const char* moduleName, const std::string& path, HalFile& file);
+  bool openFileForWrite(const char* moduleName, const String& path, HalFile& file);
   bool removeDir(const char* path);
 
   static HalStorage& getInstance() { return instance; }
 
+  class StorageLock;  // private class, used internally
+
  private:
   static HalStorage instance;
 
   bool initialized = false;
+  SemaphoreHandle_t storageMutex = nullptr;
 };
 
 #define Storage HalStorage::getInstance()
 
+class HalFile : public Print {
+  friend class HalStorage;
+  class Impl;
+  std::unique_ptr<Impl> impl;
+  explicit HalFile(std::unique_ptr<Impl> impl);
+
+ public:
+  HalFile();
+  ~HalFile();
+  HalFile(HalFile&&);
+  HalFile& operator=(HalFile&&);
+  HalFile(const HalFile&) = delete;
+  HalFile& operator=(const HalFile&) = delete;
+
+  void flush();
+  size_t getName(char* name, size_t len);
+  size_t size();
+  size_t fileSize();
+  bool seek(size_t pos);
+  bool seekCur(int64_t offset);
+  bool seekSet(size_t offset);
+  int available() const;
+  size_t position() const;
+  int read(void* buf, size_t count);
+  int read();  // read a single byte
+  size_t write(const void* buf, size_t count);
+  size_t write(uint8_t b) override;
+  bool rename(const char* newPath);
+  bool isDirectory() const;
+  void rewindDirectory();
+  bool close();
+  HalFile openNextFile();
+  bool isOpen() const;
+  operator bool() const;
+};
+
+// Only do renaming FsFile to HalFile if this header is included by downstream code
+// The renaming is to allow using the thread-safe HalFile instead of the raw FsFile, without needing to change the
+// downstream code
+#ifndef HAL_STORAGE_IMPL
+using FsFile = HalFile;
+#endif
+
 // Downstream code must use Storage instead of SdMan
 #ifdef SdMan
 #undef SdMan