Align formatter baseline with esptoolkit-template

.clang-format

@@ -0,0 +1,11 @@
+BasedOnStyle: LLVM
+ColumnLimit: 100
+BinPackArguments: false
+BinPackParameters: false
+AllowAllArgumentsOnNextLine: false
+AlignAfterOpenBracket: BlockIndent
+UseTab: ForIndentation
+IndentWidth: 4
+TabWidth: 4
+ContinuationIndentWidth: 4
+AllowShortFunctionsOnASingleLine: None

.editorconfig

@@ -0,0 +1,11 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+
+[*.{c,cc,cpp,h,hpp,ino}]
+indent_style = tab
+indent_size = tab
+tab_width = 4

.gitignore

@@ -1,4 +1,3 @@
 .venv
 build/
 build_prev_runner/
-.vscode

.vscode/bin/clang-format

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if command -v clang-format >/dev/null 2>&1; then
+    exec clang-format "$@"
+fi
+
+_home_dir="${HOME:-}"
+if [ -n "$_home_dir" ]; then
+    _candidate="$(ls -1d "$_home_dir"/.vscode/extensions/ms-vscode.cpptools-*-linux-x64/LLVM/bin/clang-format 2>/dev/null | tail -n 1 || true)"
+    if [ -n "$_candidate" ] && [ -x "$_candidate" ]; then
+        exec "$_candidate" "$@"
+    fi
+fi
+
+echo "clang-format executable not found." >&2
+echo "Install clang-format system-wide or install/update ms-vscode.cpptools." >&2
+exit 127

.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+    "recommendations": [
+        "pioarduino.pioarduino-ide",
+        "xaver.clang-format"
+    ],
+    "unwantedRecommendations": [
+        "ms-vscode.cpptools-extension-pack"
+    ]
+}

.vscode/settings.json

@@ -1,5 +1,6 @@
 {
     "files.associations": {
+        "*.ino": "cpp",
         "array": "cpp",
         "deque": "cpp",
         "string": "cpp",
@@ -8,5 +9,30 @@
         "string_view": "cpp",
         "initializer_list": "cpp",
         "cstdint": "cpp"
+    },
+    "editor.defaultFormatter": "xaver.clang-format",
+    "C_Cpp.formatting": "Disabled",
+    "clang-format.style": "file",
+    "clang-format.executable": "${workspaceRoot}/.vscode/bin/clang-format",
+    "[cpp]": {
+        "editor.defaultFormatter": "xaver.clang-format",
+        "editor.detectIndentation": false,
+        "editor.insertSpaces": false,
+        "editor.tabSize": 4,
+        "editor.formatOnSave": true
+    },
+    "[c]": {
+        "editor.defaultFormatter": "xaver.clang-format",
+        "editor.detectIndentation": false,
+        "editor.insertSpaces": false,
+        "editor.tabSize": 4,
+        "editor.formatOnSave": true
+    },
+    "[arduino]": {
+        "editor.defaultFormatter": "xaver.clang-format",
+        "editor.detectIndentation": false,
+        "editor.insertSpaces": false,
+        "editor.tabSize": 4,
+        "editor.formatOnSave": true
     }
-}
+}

.vscode/tasks.json

@@ -0,0 +1,12 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Format Firmware Sources",
+            "type": "shell",
+            "command": "bash ${workspaceFolder}/scripts/format_cpp.sh",
+            "group": "build",
+            "problemMatcher": []
+        }
+    ]
+}

CONTRIBUTING.md

@@ -134,19 +134,9 @@ Please keep these in mind when contributing:
 - **I/O**: Use `StreamUtils::WriteBufferingStream` for buffered writes.
 - **Validation**: Run schema hooks on create/update; on failure revert and return a validation error.
 - **Naming**: lowerCamelCase for methods/vars, UpperCamelCase for types, ALL_CAPS for simple constants/enums.
-- **Formatting**: Use a consistent `clang-format` (LLVM/Google); keep lines ≤ 120 cols.
+- **Formatting**: Follow the repository `.clang-format` + `.editorconfig` baseline from `esptoolkit-template` (LLVM-derived style, `ColumnLimit: 100`, tabs with width `4`, `BinPackArguments/Parameters: false`, `AllowShortFunctionsOnASingleLine: None`).
 - **Allocations**: Avoid hidden allocations in hot paths and inside event callbacks & sync loops.
 
-Optional `.clang-format` starter (Google-like):
-```yaml
-BasedOnStyle: Google
-IndentWidth: 4
-ColumnLimit: 120
-DerivePointerAlignment: false
-PointerAlignment: Left
-AllowShortFunctionsOnASingleLine: Empty
-```
-
 ---
 
 ## Commit messages & branches

README.md

@@ -161,6 +161,13 @@ Stack sizes are expressed in bytes.
 ## Tests
 An integration harness (`test/`) runs CRUD, bulk, schema, reference, and diagnostic scenarios via the `DbTester` class. Build it as a PlatformIO test or ESP-IDF component (include `test/dbTest.cpp` in your project) and run it on hardware to validate changes. Contributions that expand automated coverage are welcome.
 
+## Formatting Baseline
+
+This repository follows the firmware formatting baseline from `esptoolkit-template`:
+- `.clang-format` is the source of truth for C/C++/INO layout.
+- `.editorconfig` enforces tabs (`tab_width = 4`), LF endings, and final newline.
+- Format all tracked firmware sources with `bash scripts/format_cpp.sh`.
+
 ## License
 MIT — see [LICENSE.md](LICENSE.md).
 

examples/AsyncFileUpload/AsyncFileUpload.ino

@@ -4,9 +4,9 @@
 ESPJsonDB db;
 
 struct UploadContext {
-    const uint8_t *data = nullptr;
-    size_t total = 0;
-    size_t offset = 0;
+	const uint8_t *data = nullptr;
+	size_t total = 0;
+	size_t offset = 0;
 };
 
 static UploadContext gUploadCtx;
@@ -16,106 +16,111 @@ static volatile bool gUploadSuccess = false;
 static volatile size_t gUploadBytes = 0;
 
 DbStatus uploadPull(size_t requested, uint8_t *buffer, size_t &produced, bool &eof) {
-    if (!buffer) return {DbStatusCode::InvalidArgument, "buffer is null"};
-
-    if (gUploadCtx.offset >= gUploadCtx.total) {
-        produced = 0;
-        eof = true;
-        return {DbStatusCode::Ok, ""};
-    }
-
-    size_t remaining = gUploadCtx.total - gUploadCtx.offset;
-    size_t take = remaining < requested ? remaining : requested;
-    memcpy(buffer, gUploadCtx.data + gUploadCtx.offset, take);
-    gUploadCtx.offset += take;
-
-    produced = take;
-    eof = (gUploadCtx.offset >= gUploadCtx.total);
-    return {DbStatusCode::Ok, ""};
+	if (!buffer)
+		return {DbStatusCode::InvalidArgument, "buffer is null"};
+
+	if (gUploadCtx.offset >= gUploadCtx.total) {
+		produced = 0;
+		eof = true;
+		return {DbStatusCode::Ok, ""};
+	}
+
+	size_t remaining = gUploadCtx.total - gUploadCtx.offset;
+	size_t take = remaining < requested ? remaining : requested;
+	memcpy(buffer, gUploadCtx.data + gUploadCtx.offset, take);
+	gUploadCtx.offset += take;
+
+	produced = take;
+	eof = (gUploadCtx.offset >= gUploadCtx.total);
+	return {DbStatusCode::Ok, ""};
 }
 
 void onUploadDone(uint32_t uploadId, const DbStatus &st, size_t bytesWritten) {
-    Serial.printf("Upload %lu done: %s (%u bytes)\n",
-                  static_cast<unsigned long>(uploadId),
-                  st.ok() ? "ok" : st.message,
-                  static_cast<unsigned>(bytesWritten));
-    gUploadBytes = bytesWritten;
-    gUploadSuccess = st.ok();
-    gUploadDone = true;
+	Serial.printf(
+	    "Upload %lu done: %s (%u bytes)\n",
+	    static_cast<unsigned long>(uploadId),
+	    st.ok() ? "ok" : st.message,
+	    static_cast<unsigned>(bytesWritten)
+	);
+	gUploadBytes = bytesWritten;
+	gUploadSuccess = st.ok();
+	gUploadDone = true;
 }
 
 void setup() {
-    Serial.begin(115200);
+	Serial.begin(115200);
 
-    ESPJsonDBConfig cfg;
-    cfg.autosync = false;
+	ESPJsonDBConfig cfg;
+	cfg.autosync = false;
 
-    auto initStatus = db.init("/async_file_demo", cfg);
-    if (!initStatus.ok()) {
-        Serial.printf("DB init failed: %s\n", initStatus.message);
-        return;
-    }
+	auto initStatus = db.init("/async_file_demo", cfg);
+	if (!initStatus.ok()) {
+		Serial.printf("DB init failed: %s\n", initStatus.message);
+		return;
+	}
 
-    static uint8_t payload[1500];
-    for (size_t i = 0; i < sizeof(payload); ++i) {
-        payload[i] = static_cast<uint8_t>(i & 0xFF);
-    }
+	static uint8_t payload[1500];
+	for (size_t i = 0; i < sizeof(payload); ++i) {
+		payload[i] = static_cast<uint8_t>(i & 0xFF);
+	}
 
-    gUploadCtx.data = payload;
-    gUploadCtx.total = sizeof(payload);
-    gUploadCtx.offset = 0;
+	gUploadCtx.data = payload;
+	gUploadCtx.total = sizeof(payload);
+	gUploadCtx.offset = 0;
 
-    ESPJsonDBFileOptions opts;
-    opts.chunkSize = 128;
-    opts.overwrite = true;
+	ESPJsonDBFileOptions opts;
+	opts.chunkSize = 128;
+	opts.overwrite = true;
 
-    auto start = db.writeFileStreamAsync("uploads/telemetry.bin", uploadPull, opts, onUploadDone);
-    if (!start.status.ok()) {
-        Serial.printf("writeFileStreamAsync failed: %s\n", start.status.message);
-        return;
-    }
+	auto start = db.writeFileStreamAsync("uploads/telemetry.bin", uploadPull, opts, onUploadDone);
+	if (!start.status.ok()) {
+		Serial.printf("writeFileStreamAsync failed: %s\n", start.status.message);
+		return;
+	}
 
-    gUploadId = start.value;
-    Serial.printf("Started upload %lu\n", static_cast<unsigned long>(gUploadId));
+	gUploadId = start.value;
+	Serial.printf("Started upload %lu\n", static_cast<unsigned long>(gUploadId));
 
-    // setup() returns immediately; upload continues on background worker.
+	// setup() returns immediately; upload continues on background worker.
 }
 
 void loop() {
-    if (gUploadId == 0) {
-        delay(200);
-        return;
-    }
-
-    if (!gUploadDone) {
-        auto state = db.getFileUploadState(gUploadId);
-        if (state.status.ok()) {
-            Serial.printf("Upload state: %u\n", static_cast<unsigned>(state.value));
-        }
-        delay(250);
-        return;
-    }
-
-    // One-time verification after completion.
-    static bool verified = false;
-    if (!verified) {
-        verified = true;
-
-        if (!gUploadSuccess) {
-            Serial.println("Upload failed");
-            return;
-        }
-
-        auto file = db.readFile("uploads/telemetry.bin");
-        if (!file.status.ok()) {
-            Serial.printf("readFile failed: %s\n", file.status.message);
-            return;
-        }
-
-        Serial.printf("readFile bytes: %u (done callback bytes: %u)\n",
-                      static_cast<unsigned>(file.value.size()),
-                      static_cast<unsigned>(gUploadBytes));
-    }
-
-    delay(1000);
+	if (gUploadId == 0) {
+		delay(200);
+		return;
+	}
+
+	if (!gUploadDone) {
+		auto state = db.getFileUploadState(gUploadId);
+		if (state.status.ok()) {
+			Serial.printf("Upload state: %u\n", static_cast<unsigned>(state.value));
+		}
+		delay(250);
+		return;
+	}
+
+	// One-time verification after completion.
+	static bool verified = false;
+	if (!verified) {
+		verified = true;
+
+		if (!gUploadSuccess) {
+			Serial.println("Upload failed");
+			return;
+		}
+
+		auto file = db.readFile("uploads/telemetry.bin");
+		if (!file.status.ok()) {
+			Serial.printf("readFile failed: %s\n", file.status.message);
+			return;
+		}
+
+		Serial.printf(
+		    "readFile bytes: %u (done callback bytes: %u)\n",
+		    static_cast<unsigned>(file.value.size()),
+		    static_cast<unsigned>(gUploadBytes)
+		);
+	}
+
+	delay(1000);
 }