F1 step 1: names, read-only rules and the packed listing (host-tested)

lib/files: path parts; names checked for rename and new folder; why
something can't be renamed, moved or deleted (the Gemini cache, a file
being written or a folder holding one, the firmware's top-level
folders), and why it can't go into a folder; the viewer for a file by
its name, with a sniff for text. FileList keeps a folder's entries
packed, 256 at most, the first 256 by name whatever order the card lists
them in, and sorts by name, date or size with folders first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT

lib/files/src/file_list.cpp

@@ -0,0 +1,131 @@
+#include "file_list.h"
+
+#include <algorithm>
+#include <cctype>
+#include <cstdio>
+#include <cstring>
+#include <ctime>
+
+namespace roro::files {
+
+namespace {
+
+// Names compare letters only, whatever the case; ties by the bytes, so the order is total.
+int compareNames(const char* a, const char* b) {
+    for (const char *x = a, *y = b;; ++x, ++y) {
+        int cx = std::tolower(static_cast<unsigned char>(*x)), cy = std::tolower(static_cast<unsigned char>(*y));
+        if (cx != cy) return cx < cy ? -1 : 1;
+        if (!cx) break;
+    }
+    return std::strcmp(a, b);
+}
+
+constexpr uint32_t kYear2020 = 1577836800;
+
+std::string sizeText(uint32_t bytes) {
+    char s[16];
+    if (bytes < 1024) std::snprintf(s, sizeof s, "%u B", static_cast<unsigned>(bytes));
+    else if (bytes < 10 * 1024) std::snprintf(s, sizeof s, "%.1f KB", bytes / 1024.0);
+    else if (bytes < 1024 * 1024) std::snprintf(s, sizeof s, "%u KB", static_cast<unsigned>(bytes / 1024));
+    else if (bytes < 10u * 1024 * 1024) std::snprintf(s, sizeof s, "%.1f MB", bytes / 1048576.0);
+    else if (bytes < 1024u * 1024 * 1024) std::snprintf(s, sizeof s, "%u MB", static_cast<unsigned>(bytes / 1048576));
+    else std::snprintf(s, sizeof s, "%.1f GB", bytes / 1073741824.0);
+    return s;
+}
+
+}  // namespace
+
+void FileList::clear() {
+    std::vector<Entry>().swap(entries_);
+    std::vector<uint16_t>().swap(order_);
+    std::vector<char>().swap(names_);
+    more_ = wasted_ = 0;
+}
+
+bool FileList::before(const Entry& a, const Entry& b, FileSort by) const {
+    if (a.folder != b.folder) return a.folder;
+    if (!a.folder) {
+        if (by == FileSort::Date && a.modified != b.modified) return a.modified > b.modified;
+        if (by == FileSort::Size && a.size != b.size) return a.size > b.size;
+    }
+    return compareNames(names_.data() + a.name, names_.data() + b.name) < 0;
+}
+
+void FileList::add(const char* name, uint32_t size, uint32_t modified, bool folder) {
+    size_t len = std::strlen(name) + 1;
+    if (entries_.size() >= kMax) {
+        // Full: the new entry takes the place of the one that sorts last by name, if it sorts
+        // before it. The old name's bytes stay in the buffer until there's enough waste to pack.
+        more_++;
+        size_t last = 0;
+        for (size_t i = 1; i < entries_.size(); i++)
+            if (before(entries_[last], entries_[i], FileSort::Name)) last = i;
+        Entry candidate{static_cast<uint32_t>(names_.size()), size, modified, folder};
+        names_.insert(names_.end(), name, name + len);
+        if (!before(candidate, entries_[last], FileSort::Name)) {
+            names_.resize(names_.size() - len);
+            return;
+        }
+        wasted_ += std::strlen(names_.data() + entries_[last].name) + 1;
+        entries_[last] = candidate;
+        if (wasted_ > 2048) compact();
+        return;
+    }
+    if (entries_.empty()) {
+        entries_.reserve(32);
+        names_.reserve(512);
+    }
+    entries_.push_back({static_cast<uint32_t>(names_.size()), size, modified, folder});
+    names_.insert(names_.end(), name, name + len);
+    order_.push_back(static_cast<uint16_t>(order_.size()));
+}
+
+void FileList::compact() {
+    std::vector<char> packed;
+    packed.reserve(names_.size() - wasted_);
+    for (Entry& e : entries_) {
+        const char* n = names_.data() + e.name;
+        e.name = static_cast<uint32_t>(packed.size());
+        packed.insert(packed.end(), n, n + std::strlen(n) + 1);
+    }
+    names_.swap(packed);
+    wasted_ = 0;
+}
+
+void FileList::sort(FileSort by) {
+    if (wasted_) compact();
+    names_.shrink_to_fit();
+    entries_.shrink_to_fit();
+    order_.resize(entries_.size());
+    for (size_t i = 0; i < order_.size(); i++) order_[i] = static_cast<uint16_t>(i);
+    std::sort(order_.begin(), order_.end(), [&](uint16_t a, uint16_t b) { return before(entries_[a], entries_[b], by); });
+}
+
+int FileList::find(const std::string& name) const {
+    for (size_t i = 0; i < order_.size(); i++)
+        if (name == this->name(i)) return static_cast<int>(i);
+    return -1;
+}
+
+size_t FileList::bytes() const {
+    return entries_.capacity() * sizeof(Entry) + order_.capacity() * sizeof(uint16_t) + names_.capacity();
+}
+
+std::string formatStamp(uint32_t modified) {
+    if (modified < kYear2020) return "-";
+    time_t t = static_cast<time_t>(modified);
+    struct tm local;
+    localtime_r(&t, &local);
+    char s[20];
+    std::snprintf(s, sizeof s, "%04d-%02d-%02d %02d:%02d", local.tm_year + 1900, local.tm_mon + 1, local.tm_mday, local.tm_hour,
+                  local.tm_min);
+    return s;
+}
+
+std::string rowDetail(bool folder, uint32_t size, uint32_t modified) {
+    if (folder) return "folder";
+    std::string stamp = formatStamp(modified);
+    return sizeText(size) + "  " + (stamp == "-" ? stamp : stamp.substr(0, 10));
+}
+
+}  // namespace roro::files

lib/files/src/file_list.h

@@ -0,0 +1,53 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace roro::files {
+
+enum class FileSort : uint8_t { Name, Date, Size };
+
+// A folder's entries for the Storage App (F1, Q129, Q136): 256 at most, the names packed into
+// one buffer, about 10 KB when full. A bigger folder keeps the first 256 by name, whatever order
+// the card lists them in, and counts the rest.
+class FileList {
+   public:
+    static constexpr size_t kMax = 256;
+
+    void clear();
+    void add(const char* name, uint32_t size, uint32_t modified, bool folder);
+    void sort(FileSort by);  // folders first, by name; then files by name, newest or biggest first
+
+    size_t count() const { return entries_.size(); }
+    size_t more() const { return more_; }  // entries that didn't fit
+    // By position after sort().
+    const char* name(size_t i) const { return names_.data() + entries_[order_[i]].name; }
+    uint32_t size(size_t i) const { return entries_[order_[i]].size; }
+    uint32_t modified(size_t i) const { return entries_[order_[i]].modified; }  // Unix time, 0 if unknown
+    bool folder(size_t i) const { return entries_[order_[i]].folder; }
+    int find(const std::string& name) const;  // position, or -1
+    size_t bytes() const;                     // memory held
+
+   private:
+    struct Entry {
+        uint32_t name;  // offset into names_
+        uint32_t size, modified;
+        bool folder;
+    };
+    bool before(const Entry& a, const Entry& b, FileSort by) const;
+    void compact();
+
+    std::vector<Entry> entries_;
+    std::vector<uint16_t> order_;
+    std::vector<char> names_;
+    size_t more_ = 0, wasted_ = 0;
+};
+
+// What a row shows on the right (Q129): "folder", or "1.2 KB  2026-10-05". A file dated before
+// 2020 was written before the clock was set: "-" (Q137). Local time.
+std::string rowDetail(bool folder, uint32_t size, uint32_t modified);
+std::string formatStamp(uint32_t modified);  // "2026-10-05 20:00", or "-"
+
+}  // namespace roro::files

lib/files/src/file_names.cpp

@@ -0,0 +1,99 @@
+#include "file_names.h"
+
+#include <cctype>
+
+namespace roro::files {
+
+const char* const kFirmwareFolders[] = {"/irc", "/wifi", "/updates", "/gnss", "/gemini", "/captures", "/notes"};
+const size_t kFirmwareFolderCount = sizeof kFirmwareFolders / sizeof kFirmwareFolders[0];
+
+std::string parentOf(const std::string& path) {
+    size_t slash = path.rfind('/');
+    return slash == std::string::npos || slash == 0 ? "/" : path.substr(0, slash);
+}
+
+std::string baseName(const std::string& path) {
+    size_t slash = path.rfind('/');
+    return slash == std::string::npos ? path : path.substr(slash + 1);
+}
+
+std::string joinPath(const std::string& folder, const std::string& name) {
+    return folder == "/" ? "/" + name : folder + "/" + name;
+}
+
+std::string extensionOf(const std::string& name) {
+    size_t dot = name.rfind('.');
+    if (dot == std::string::npos || dot == 0) return "";
+    std::string ext = name.substr(dot + 1);
+    for (char& c : ext) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+    return ext;
+}
+
+bool isInside(const std::string& path, const std::string& folder) {
+    if (folder == "/") return true;
+    if (path.compare(0, folder.size(), folder) != 0) return false;
+    return path.size() == folder.size() || path[folder.size()] == '/';
+}
+
+std::string checkName(const std::string& name) {
+    if (name.empty()) return "A name can't be empty";
+    if (name == "." || name == "..") return "\".\" and \"..\" aren't names";
+    if (name.size() > 64) return "A name can be 64 characters at most";
+    for (char c : name) {
+        if (static_cast<unsigned char>(c) < 0x20) return "A name can't contain control characters";
+        for (char bad : std::string("/\\:*?\"<>|"))
+            if (c == bad) return std::string("A name can't contain ") + c;
+    }
+    if (name.back() == '.' || name.back() == ' ') return "A name can't end with a dot or a space";
+    return "";
+}
+
+std::string whyReadOnly(const std::string& path, const std::vector<std::string>& inUse) {
+    if (path == "/" || path.empty()) return "That's the card itself";
+    if (isInside(path, kGeminiCache)) return std::string(kGeminiCache) + " is the Gemini App's working space";
+    for (const std::string& open : inUse) {
+        if (open == path) return "It's being written right now";
+        if (isInside(open, path)) return "It holds a file that's being written right now";
+    }
+    for (size_t i = 0; i < kFirmwareFolderCount; i++)
+        if (path == kFirmwareFolders[i]) return std::string("The firmware keeps its files in ") + path;
+    return "";
+}
+
+std::string whyNotInto(const std::string& source, const std::string& into) {
+    if (isInside(into, kGeminiCache)) return std::string(kGeminiCache) + " is the Gemini App's working space";
+    if (isInside(into, source)) return "A folder can't go inside itself";
+    if (parentOf(source) == into) return "It's already there";
+    return "";
+}
+
+std::string copyName(const std::string& name, int n) {
+    size_t dot = name.rfind('.');
+    std::string suffix = " (" + std::to_string(n) + ")";
+    if (dot == std::string::npos || dot == 0) return name + suffix;
+    return name.substr(0, dot) + suffix + name.substr(dot);
+}
+
+FileKind kindOf(const std::string& name) {
+    std::string ext = extensionOf(name);
+    if (ext == "gpx") return FileKind::Gpx;
+    if (ext == "pcap") return FileKind::Pcap;
+    if (ext == "ota") return FileKind::Ota;
+    for (const char* text : {"txt", "log", "gmi", "csv", "md", "json", "ini", "conf", "ir"})
+        if (ext == text) return FileKind::Text;
+    return FileKind::Unknown;
+}
+
+bool opensAtEnd(const std::string& name) { return extensionOf(name) == "log"; }
+
+bool looksLikeText(const uint8_t* data, size_t len) {
+    size_t odd = 0;
+    for (size_t i = 0; i < len; i++) {
+        uint8_t b = data[i];
+        if (b == 0) return false;
+        if (b < 0x20 && b != '\n' && b != '\r' && b != '\t') odd++;
+    }
+    return odd * 20 <= len;  // a stray control character or two is still text
+}
+
+}  // namespace roro::files

lib/files/src/file_names.h

@@ -0,0 +1,42 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace roro::files {
+
+// Paths on the SD card are absolute and use '/': "/gemini/saved/index.gmi".
+std::string parentOf(const std::string& path);    // "/" for a top-level entry and for "/"
+std::string baseName(const std::string& path);    // "" for "/"
+std::string joinPath(const std::string& folder, const std::string& name);
+std::string extensionOf(const std::string& name);  // lower case, without the dot; "" if none
+bool isInside(const std::string& path, const std::string& folder);  // a folder is inside itself
+
+// A name typed for rename or a new folder (F1, Q131): "" if FAT and this App can take it, or why not.
+std::string checkName(const std::string& name);
+
+// The top-level folders the firmware keeps its files in. They can't be renamed or deleted;
+// what's in them can (Q130).
+extern const char* const kFirmwareFolders[];
+extern const size_t kFirmwareFolderCount;
+constexpr const char* kGeminiCache = "/gemini/cache";
+
+// Why `path` can't be renamed, moved or deleted, or "" if it can (Q130). `inUse`: the files the
+// firmware has open right now.
+std::string whyReadOnly(const std::string& path, const std::vector<std::string>& inUse);
+
+// Why `source` can't be copied or moved into the folder `into`, or "" if it can.
+std::string whyNotInto(const std::string& source, const std::string& into);
+
+// "a (2).gmi": the name of a copy made next to its original.
+std::string copyName(const std::string& name, int n);
+
+// Which viewer opens a file (Q134), from its name. Unknown: look at the first bytes.
+enum class FileKind : uint8_t { Text, Gpx, Pcap, Ota, Unknown };
+FileKind kindOf(const std::string& name);
+bool opensAtEnd(const std::string& name);  // logs
+bool looksLikeText(const uint8_t* data, size_t len);
+
+}  // namespace roro::files