feat(util): add StrPrintf for single-allocation printf-style formatting

Two-pass vsnprintf pattern (Chromium/Android standard) that measures
exact size first, then allocates once. Prevents heap fragmentation
on ESP32 (320KB RAM) for large RAG contexts (4KB+).

Includes MSVC guard for __attribute__((format)) and 14 test cases.

Author: konegen

include/foresthub/util/strprintf.hpp

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 ForestHub. All rights reserved.
+// For commercial licensing, visit https://github.com/ForestHubAI/fh-sdk
+
+#ifndef FORESTHUB_UTIL_STRPRINTF_HPP
+#define FORESTHUB_UTIL_STRPRINTF_HPP
+
+/// @file
+/// Printf-style string formatting with single heap allocation.
+
+#include <cstdarg>
+#include <cstdio>
+#include <string>
+
+namespace foresthub {
+namespace util {
+
+/// Builds a std::string using printf-style formatting.
+///
+/// Uses a two-pass vsnprintf approach: first measures the exact output size,
+/// then allocates once and writes. This avoids heap fragmentation from
+/// repeated std::string concatenation on memory-constrained embedded devices.
+///
+/// @warning The format string must not contain untrusted user input.
+///          Pass user data as arguments, never as the format string.
+///
+/// @param fmt  printf-style format string
+/// @param ...  arguments matching the format specifiers
+/// @return     formatted std::string (empty on encoding error)
+#if defined(__GNUC__) || defined(__clang__)
+// GCC/Clang: Enable compile-time format string checking.
+// Argument indices: 1 = format string, 2 = first vararg (free function, no implicit 'this')
+inline std::string StrPrintf(const char* fmt, ...) __attribute__((format(printf, 1, 2)));
+#else
+inline std::string StrPrintf(const char* fmt, ...);
+#endif
+
+inline std::string StrPrintf(const char* fmt, ...) {
+    va_list args1, args2;
+    va_start(args1, fmt);
+    va_copy(args2, args1);
+
+    int len = vsnprintf(nullptr, 0, fmt, args1);  // Pass 1: measure exact size
+    va_end(args1);
+
+    if (len <= 0) {
+        va_end(args2);
+        return "";
+    }
+
+    std::string result(static_cast<size_t>(len), '\0');               // ONE allocation, exact size
+    vsnprintf(&result[0], static_cast<size_t>(len) + 1, fmt, args2);  // Pass 2: write
+    va_end(args2);
+
+    return result;  // RVO - no copy
+}
+
+}  // namespace util
+}  // namespace foresthub
+
+#endif  // FORESTHUB_UTIL_STRPRINTF_HPP

tests/CMakeLists.txt

@@ -48,6 +48,7 @@ gtest_discover_tests(run_agent_tests)
 add_executable(run_util_tests
     util/optional_test.cpp
     util/schema_test.cpp
+    util/strprintf_test.cpp
     util/ticker_test.cpp
 )
 

tests/util/strprintf_test.cpp

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 ForestHub. All rights reserved.
+// For commercial licensing, visit https://github.com/ForestHubAI/fh-sdk
+
+#include "foresthub/util/strprintf.hpp"
+
+#include <gtest/gtest.h>
+
+#include <string>
+
+using foresthub::util::StrPrintf;
+
+// ==========================================================================
+// 1. Basic Formatting
+// ==========================================================================
+
+TEST(StrPrintfTest, EmptyFormatString) {
+    EXPECT_EQ(StrPrintf(""), "");
+}
+
+TEST(StrPrintfTest, PlainTextNoArgs) {
+    EXPECT_EQ(StrPrintf("hello"), "hello");
+}
+
+TEST(StrPrintfTest, StringArg) {
+    EXPECT_EQ(StrPrintf("name: %s", "Alice"), "name: Alice");
+}
+
+TEST(StrPrintfTest, IntArg) {
+    EXPECT_EQ(StrPrintf("count: %d", 42), "count: 42");
+}
+
+TEST(StrPrintfTest, FloatArg) {
+    std::string result = StrPrintf("temp: %f", 3.14);
+    EXPECT_EQ(result.substr(0, 10), "temp: 3.14");
+}
+
+TEST(StrPrintfTest, MixedArgs) {
+    EXPECT_EQ(StrPrintf("%s = %d", "x", 5), "x = 5");
+}
+
+TEST(StrPrintfTest, PercentEscaping) {
+    EXPECT_EQ(StrPrintf("100%%"), "100%");
+}
+
+// ==========================================================================
+// 2. Type-Specific Formatting
+// ==========================================================================
+
+TEST(StrPrintfTest, NegativeInt) {
+    EXPECT_EQ(StrPrintf("n: %d", -42), "n: -42");
+}
+
+TEST(StrPrintfTest, BoolAsInt) {
+    EXPECT_EQ(StrPrintf("flag: %d", static_cast<int>(true)), "flag: 1");
+    EXPECT_EQ(StrPrintf("flag: %d", static_cast<int>(false)), "flag: 0");
+}
+
+TEST(StrPrintfTest, FloatPrecision) {
+    EXPECT_EQ(StrPrintf("val: %.2f", 3.14159), "val: 3.14");
+}
+
+// ==========================================================================
+// 3. std::string Integration
+// ==========================================================================
+
+TEST(StrPrintfTest, StdStringCStr) {
+    std::string name = "Bob";
+    EXPECT_EQ(StrPrintf("hello %s", name.c_str()), "hello Bob");
+}
+
+TEST(StrPrintfTest, MultipleStringArgs) {
+    std::string a = "foo";
+    std::string b = "bar";
+    EXPECT_EQ(StrPrintf("%s und Kontext: %s", a.c_str(), b.c_str()), "foo und Kontext: bar");
+}
+
+// ==========================================================================
+// 4. Large Strings
+// ==========================================================================
+
+TEST(StrPrintfTest, LargeString) {
+    std::string payload(2048, 'X');
+    std::string result = StrPrintf("data: %s", payload.c_str());
+    EXPECT_EQ(result.size(), 6 + 2048);  // "data: " + payload
+    EXPECT_EQ(result.substr(0, 6), "data: ");
+    EXPECT_EQ(result.back(), 'X');
+}
+
+TEST(StrPrintfTest, LargeFormatResult) {
+    // Simulate RAG-style output >4KB
+    std::string ctx(4096, 'A');
+    std::string serial(1024, 'B');
+    std::string result = StrPrintf("%s und Kontext: %s", serial.c_str(), ctx.c_str());
+    EXPECT_EQ(result.size(), 1024 + 14 + 4096);  // serial + " und Kontext: " + ctx
+}