Add persistent script storage + hot-reload, verified live

lua_runtime now loads the running script from a new LittleFS-backed
drivers::storage (joltwallet/littlefs, the project's fifth external
managed component -- mounts the "storage" partition already reserved
in partitions.csv), falling back to the compiled-in default script
only on first boot. transport exposes GET/POST /api/script -- raw Lua
text, not JSON, since json_helpers.h can't round-trip scripts safely
-- relayed to lua_runtime via the same callback-registration pattern
already used for LedColorHandler, keeping transport free of a
dependency on lua_runtime. lua_runtime_reload() persists and hot-swaps
to a fresh Lua state immediately, no reboot.

Verified on real ESP32-C6 hardware: script loads via kvida-sdk, an
edited script hot-reloads within one tick, and the edit survives a
power cycle (proving LittleFS persistence, not just an in-RAM change).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

components/transport/README.md

@@ -34,6 +34,7 @@ Both httpd servers (the commissioning AP's and the settings server's) expose a s
 - `POST /api/wifi` (commissioning AP only) -- `{"ssid","password"}`, replaces the old form-urlencoded `/connect`.
 - `GET /api/status` (settings server) -- `{"device_id","wifi_connected","mqtt_connected"}`.
 - `GET /api/mqtt` / `POST /api/mqtt` (settings server) -- `{"host","port","username"[,"password"]}`; `GET` never returns the password.
+- `GET /api/script` / `POST /api/script` (settings server) -- the one endpoint in this API that is **not** JSON: the body is the raw Lua source as `text/plain`, both directions. Deliberate, not an oversight -- `json_helpers.h` is explicitly a non-escaping minimal parser, and Lua scripts routinely contain `"`, `\`, and newlines it can't round-trip safely. `transport` doesn't store or interpret the script itself (would mean depending on `lua_runtime`, breaking this component's "no dependency on other Kvida components" rule) -- it just relays through two function-pointer callbacks main.cpp wires up, `set_script_change_handler`/`set_script_provider`, the same pattern already used for `LedColorHandler`. `POST` reads the body in a loop up to an 8KB cap (`413` beyond that) since, unlike the small fixed-shape JSON bodies elsewhere here, `httpd_req_recv()` isn't guaranteed to return a script-sized body in one call.
 
 No JSON library ships with ESP-IDF v6.0.2 core (verified: no `cJSON`, no bundled `json` component). Given these payloads are tiny, flat, fixed-shape objects, `src/json_helpers.h` hand-rolls minimal `strstr`-based extraction rather than adding a 4th external registry dependency (already have `mdns`, `mqtt`, `led_strip`) -- explicitly not a general parser (no nesting, arrays, or escaping beyond what these specific request bodies need).
 

components/transport/include/mqtt.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#include <cstddef>
 #include <cstdint>
 
 namespace kvida {
@@ -29,4 +30,17 @@ void publish_value(const char *name, double value);
 using LedColorHandler = void (*)(uint8_t red, uint8_t green, uint8_t blue);
 void set_led_color_handler(LedColorHandler handler);
 
+// Same no-dependency-on-other-components pattern as LedColorHandler:
+// registered by main so a POST to /api/script can hand the new script to
+// `lua_runtime` without transport depending on it. `script` is not
+// NUL-terminated by the caller's guarantee -- handlers must use `len`.
+using ScriptChangeHandler = void (*)(const char *script, size_t len);
+void set_script_change_handler(ScriptChangeHandler handler);
+
+// Registered by main so GET /api/script can pull the currently-running
+// script from `lua_runtime`. Called with a buffer of size `cap`; returns
+// the number of bytes written (0 if no provider is registered yet).
+using ScriptProvider = size_t (*)(char *buf, size_t cap);
+void set_script_provider(ScriptProvider provider);
+
 } // namespace kvida

components/transport/src/mqtt.cpp

@@ -38,6 +38,12 @@ esp_mqtt_client_handle_t g_client = nullptr;
 esp_timer_handle_t g_retry_timer = nullptr;
 httpd_handle_t g_settings_httpd = nullptr;
 LedColorHandler g_led_handler = nullptr;
+ScriptChangeHandler g_script_change_handler = nullptr;
+ScriptProvider g_script_provider = nullptr;
+
+// Matches lua_runtime's g_script buffer size -- a script that doesn't fit
+// in either is rejected the same way.
+constexpr size_t kMaxScriptSize = 8192;
 
 char g_availability_topic[48];
 char g_discovery_topic[80];
@@ -451,6 +457,64 @@ esp_err_t api_mqtt_post_handler(httpd_req_t *req)
     return ESP_OK;
 }
 
+// GET /api/script -- the currently-running Lua script, raw text (not
+// JSON: see the POST handler's comment for why).
+esp_err_t api_script_get_handler(httpd_req_t *req)
+{
+    add_cors_headers(req);
+
+    if (!g_script_provider) {
+        httpd_resp_set_status(req, "503 Service Unavailable");
+        httpd_resp_send(req, "", 0);
+        return ESP_OK;
+    }
+
+    static char buf[kMaxScriptSize];
+    size_t len = g_script_provider(buf, sizeof(buf));
+
+    httpd_resp_set_type(req, "text/plain");
+    httpd_resp_send(req, buf, len);
+    return ESP_OK;
+}
+
+// POST /api/script -- body is the raw Lua source, not JSON. Scripts
+// routinely contain '"', '\', and newlines that json_helpers.h's
+// non-escaping parser (see its own header comment) can't round-trip
+// safely, so this endpoint skips JSON entirely. httpd_req_recv() isn't
+// guaranteed to return the whole body in one call once it's more than a
+// few hundred bytes (unlike the small fixed-shape JSON bodies elsewhere
+// in this file), so this reads in a loop until content_len bytes are in.
+esp_err_t api_script_post_handler(httpd_req_t *req)
+{
+    add_cors_headers(req);
+
+    if (req->content_len == 0 || req->content_len >= kMaxScriptSize) {
+        httpd_resp_set_status(req, "413 Payload Too Large");
+        httpd_resp_set_type(req, "application/json");
+        httpd_resp_send(req, "{\"error\":\"script too large\"}", HTTPD_RESP_USE_STRLEN);
+        return ESP_OK;
+    }
+
+    static char body[kMaxScriptSize];
+    size_t received = 0;
+    while (received < req->content_len) {
+        int ret = httpd_req_recv(req, body + received, req->content_len - received);
+        if (ret <= 0) {
+            httpd_resp_send_500(req);
+            return ESP_FAIL;
+        }
+        received += static_cast<size_t>(ret);
+    }
+
+    if (g_script_change_handler) {
+        g_script_change_handler(body, received);
+    }
+
+    httpd_resp_set_type(req, "application/json");
+    httpd_resp_send(req, "{\"status\":\"reloaded\"}", HTTPD_RESP_USE_STRLEN);
+    return ESP_OK;
+}
+
 esp_err_t api_options_handler(httpd_req_t *req)
 {
     return cors_preflight_handler(req);
@@ -486,7 +550,7 @@ void start_settings_server()
 
     httpd_config_t config = HTTPD_DEFAULT_CONFIG();
     config.lru_purge_enable = true;
-    config.max_uri_handlers = 12;
+    config.max_uri_handlers = 15;
     if (httpd_start(&g_settings_httpd, &config) != ESP_OK) {
         ESP_LOGE(TAG, "Failed to start settings HTTP server");
         return;
@@ -502,11 +566,20 @@ void start_settings_server()
         .uri = "/api/mqtt", .method = HTTP_POST, .handler = api_mqtt_post_handler, .user_ctx = nullptr};
     static const httpd_uri_t mqtt_options_uri = {
         .uri = "/api/mqtt", .method = HTTP_OPTIONS, .handler = api_options_handler, .user_ctx = nullptr};
+    static const httpd_uri_t script_get_uri = {
+        .uri = "/api/script", .method = HTTP_GET, .handler = api_script_get_handler, .user_ctx = nullptr};
+    static const httpd_uri_t script_post_uri = {
+        .uri = "/api/script", .method = HTTP_POST, .handler = api_script_post_handler, .user_ctx = nullptr};
+    static const httpd_uri_t script_options_uri = {
+        .uri = "/api/script", .method = HTTP_OPTIONS, .handler = api_options_handler, .user_ctx = nullptr};
     httpd_register_uri_handler(g_settings_httpd, &root_uri);
     httpd_register_uri_handler(g_settings_httpd, &status_uri);
     httpd_register_uri_handler(g_settings_httpd, &mqtt_get_uri);
     httpd_register_uri_handler(g_settings_httpd, &mqtt_post_uri);
     httpd_register_uri_handler(g_settings_httpd, &mqtt_options_uri);
+    httpd_register_uri_handler(g_settings_httpd, &script_get_uri);
+    httpd_register_uri_handler(g_settings_httpd, &script_post_uri);
+    httpd_register_uri_handler(g_settings_httpd, &script_options_uri);
 }
 
 } // namespace
@@ -590,4 +663,14 @@ void set_led_color_handler(LedColorHandler handler)
     g_led_handler = handler;
 }
 
+void set_script_change_handler(ScriptChangeHandler handler)
+{
+    g_script_change_handler = handler;
+}
+
+void set_script_provider(ScriptProvider provider)
+{
+    g_script_provider = provider;
+}
+
 } // namespace kvida