@polderlabs/bizar 6.2.5 → 6.3.0

package/.claude/skills/cpp-coding-standards/references/memory-safety.md

@@ -0,0 +1,216 @@
+# Memory Safety in Modern C++
+
+This reference covers RAII, smart pointers, and the Rule of Five/Zero.
+
+## RAII — Resource Acquisition Is Initialization
+
+Every resource (heap memory, file handle, mutex, socket, etc.) must be owned by an object whose destructor performs cleanup. This guarantees cleanup even when exceptions are thrown.
+
+```cpp
+// GOOD — file closes automatically at scope exit
+void read_file(const std::string& path) {
+    std::ifstream in(path);
+    std::string line;
+    while (std::getline(in, line)) {
+        process(line);
+    }
+} // destructor closes file, no matter how we exit
+
+// BAD — manual cleanup, error-prone
+void read_file_bad(const std::string& path) {
+    std::ifstream* in = new std::ifstream(path);
+    std::string line;
+    while (std::getline(*in, line)) {  // throws? leaks *in
+        process(line);
+    }
+    delete in;
+}
+```
+
+### Common RAII Types in the Standard Library
+
+| Type | Resource |
+|---|---|
+| `std::unique_ptr` | Heap memory (single owner) |
+| `std::shared_ptr` | Heap memory (shared owner) |
+| `std::ifstream` / `std::ofstream` | File handles |
+| `std::lock_guard` / `std::scoped_lock` | Mutex lock |
+| `std::jthread` (C++20) | Thread join on destruction |
+
+## Smart Pointers
+
+### `std::unique_ptr<T>`
+
+Exclusive ownership. The default choice. Zero overhead over raw pointer.
+
+```cpp
+#include <memory>
+
+// Creation
+auto p1 = std::make_unique<int>(42);
+auto p2 = std::make_unique<std::vector<int>>(10, 0);
+
+// Custom deleter (rare — only when type needs special cleanup)
+auto file_deleter = [](FILE* f) { if (f) fclose(f); };
+std::unique_ptr<FILE, decltype(file_deleter)> fp(fopen("data.txt", "r"), file_deleter);
+
+// Transfer ownership
+std::unique_ptr<int> source = std::make_unique<int>(1);
+std::unique_ptr<int> dest = std::move(source);  // source is now nullptr
+assert(!source);
+assert(*dest == 1);
+
+// Release the raw pointer (rare — only for C interop)
+int* raw = p1.release();
+delete raw;  // you now own it — avoid this
+```
+
+### `std::shared_ptr<T>`
+
+Shared ownership via reference counting. Use **only** when ownership genuinely must be shared. Prefer `unique_ptr` otherwise.
+
+```cpp
+auto shared = std::make_shared<int>(100);
+
+// Copy increases ref count
+auto shared2 = shared;  // ref count = 2
+
+// shared_ptr can be created from unique_ptr
+auto unique = std::make_unique<double>(3.14);
+std::shared_ptr<double> from_unique = std::move(unique);
+
+// Weak pointer — breaks cycles
+std::weak_ptr<int> weak = shared;
+if (auto locked = weak.lock()) {
+    // use *locked safely
+}  // locked goes out of scope, ref count unchanged
+
+// Custom deleter — stored separately from the control block
+auto deleter = [](FILE* f) { fclose(f); };
+std::shared_ptr<FILE> f(fopen("x.txt", "r"), deleter);
+```
+
+**Performance notes:**
+- `shared_ptr` is twice the size of a raw pointer (control block + pointer)
+- Atomic reference count increments/decrements on copy/destroy
+- `make_shared` allocates the object and control block in one allocation (preferred)
+
+### `std::weak_ptr<T>`
+
+Non-owning observer of a `shared_ptr`. Use to break reference cycles (A owns B, B observes A without owning).
+
+```cpp
+class Observer;
+class Subject {
+    std::vector<std::weak_ptr<Observer>> observers_;
+public:
+    void notify() {
+        for (auto& w : observers_) {
+            if (auto o = w.lock()) o->on_update();
+        }
+    }
+};
+```
+
+## Rule of Five
+
+If you define **any one** of the five special member functions below, you likely need to define **all five**:
+
+1. Destructor
+2. Copy constructor
+3. Copy assignment operator
+4. Move constructor
+5. Move assignment operator
+
+```cpp
+class Buffer {
+    int* data_ = nullptr;
+    size_t size_ = 0;
+public:
+    explicit Buffer(size_t n) : data_(new int[n]), size_(n) {}
+
+    ~Buffer() { delete[] data_; }
+
+    // Copy constructor
+    Buffer(const Buffer& o) : data_(new int[o.size_]), size_(o.size_) {
+        std::copy(o.data_, o.data_ + o.size_, data_);
+    }
+
+    // Copy assignment operator
+    Buffer& operator=(const Buffer& o) {
+        if (this != &o) {
+            delete[] data_;
+            data_ = new int[o.size_];
+            size_ = o.size_;
+            std::copy(o.data_, o.data_ + o.size_, data_);
+        }
+        return *this;
+    }
+
+    // Move constructor
+    Buffer(Buffer&& o) noexcept : data_(std::exchange(o.data_, nullptr)), size_(std::exchange(o.size_, 0)) {}
+
+    // Move assignment operator
+    Buffer& operator=(Buffer&& o) noexcept {
+        if (this != &o) {
+            delete[] data_;
+            data_ = std::exchange(o.data_, nullptr);
+            size_ = std::exchange(o.size_, 0);
+        }
+        return *this;
+    }
+};
+```
+
+## Rule of Zero
+
+Prefer **not** defining any special members and letting the compiler generate them correctly. Use standard library containers and smart pointers to manage resources.
+
+```cpp
+// Rule of Zero — no manual resource management needed
+class Point {
+    double x_ = 0, y_ = 0;
+public:
+    Point() = default;
+    Point(double x, double y) : x_(x), y_(y) {}
+    double distance_to(const Point& o) const {
+        double dx = x_ - o.x_, dy = y_ - o.y_;
+        return std::sqrt(dx*dx + dy*dy);
+    }
+};
+// Compiler-generated copy/move/dtor are all correct here
+```
+
+## Common Mistakes
+
+```cpp
+// WRONG: Shared ownership where unique ownership suffices
+auto widget = std::make_shared<Widget>();
+process(std::shared_ptr<Widget>(widget));  // unnecessary ref count bump
+
+// WRONG: Memory leak via raw new in container
+std::vector<int*> v;
+v.push_back(new int(1));  // who deletes these?
+
+// RIGHT: Smart pointers in containers
+std::vector<std::unique_ptr<int>> v;
+v.push_back(std::make_unique<int>(1));  // auto-deleted
+
+// WRONG: Missing virtual destructor in base class
+struct Base {
+    virtual void foo() {}
+    // Missing virtual destructor — deleting through base pointer is UB
+};
+struct Derived : Base {
+    std::vector<int> data;
+};
+
+Base* b = new Derived;
+delete b;  // UB: Derived's destructor not called
+
+// RIGHT: Virtual destructor
+struct Base {
+    virtual ~Base() = default;  // polymorphic bases need virtual dtor
+    virtual void foo() {}
+};
+```

package/.claude/skills/cpp-coding-standards/references/modern-idioms.md

@@ -0,0 +1,282 @@
+# Modern C++17/20 Idioms
+
+This reference covers the most impactful modern C++ features with minimal examples.
+
+## Structured Bindings
+
+Unpack tuples, pairs, structs, and arrays into named variables.
+
+```cpp
+#include <tuple>
+#include <map>
+
+// Pair/tuple
+auto [key, value] = std::pair{1, std::string("hello")};
+
+// Array
+auto [a, b, c] = std::array{1, 2, 3};
+
+// Struct — works if all members are public
+struct Point { double x, y, z; };
+Point p{1.0, 2.0, 3.0};
+auto [px, py, pz] = p;
+
+// Map iteration
+std::map<std::string, int> ages{{"Alice", 30}, {"Bob", 25}};
+for (const auto& [name, age] : ages) {
+    std::cout << name << ": " << age << '\n';
+}
+
+// Multiple return values
+std::tuple<int, std::string, double> compute() { return {42, "answer", 3.14}; }
+auto [code, label, score] = compute();
+```
+
+## `if constexpr`
+
+Compile-time conditional code execution — the unselected branch is not instantiated.
+
+```cpp
+#include <type_traits>
+
+template <typename T>
+auto inspect(const T& val) {
+    if constexpr (std::is_integral_v<T>) {
+        return "integer";
+    } else if constexpr (std::is_floating_point_v<T>) {
+        return "floating-point";
+    } else {
+        return "other";
+    }
+}
+
+// Works where SFINAE would require complex enable_if
+template <typename T>
+T doubled(T x) {
+    if constexpr (std::is_integral_v<T>) {
+        return x + x;  // valid only for integral T
+    } else {
+        return x * 2.0;  // valid only for floating-point T
+    }
+}
+```
+
+## `std::optional`
+
+Represents a value that may or may not be present. Alternative to pointer-returning APIs.
+
+```cpp
+#include <optional>
+
+// Return optional
+std::optional<int> find_index(const std::vector<int>& v, int target) {
+    for (auto it = v.begin(); it != v.end(); ++it) {
+        if (*it == target)
+            return {static_cast<int>(std::distance(v.begin(), it))};
+    }
+    return std::nullopt;
+}
+
+// Check and use
+if (auto idx = find_index(vec, 42)) {
+    std::cout << "Found at " << *idx << '\n';
+} else {
+    std::cout << "Not found\n";
+}
+
+// Transform an optional without unwrapping
+std::optional<std::string> name = /* ... */;
+auto greeting = name.transform([](const std::string& n) { return "Hello, " + n; });
+```
+
+## `std::string_view`
+
+Non-owning view into a string. Use for read-only string operations without copying.
+
+```cpp
+#include <string_view>
+
+// Function takes a view — no ownership, no allocation
+bool ends_with(std::string_view s, std::string_view suffix) {
+    return s.size() >= suffix.size() && s.substr(s.size() - suffix.size()) == suffix;
+}
+
+// Calling with different string types — no conversion/copy
+std::string s = "filename.txt";
+std::string_view sv = s;
+ends_with(sv, ".txt");           // string_view
+ends_with("literal", ".txt");    // const char* converts to string_view
+ends_with(sv, std::string(".log"));  // string converts to string_view
+
+// AVOID: storing string_view as a class member — it doesn't own the data
+// (only safe if another owning string keeps the data alive)
+```
+
+## `std::variant` (C++17)
+
+Type-safe union — an object that holds one of several specified types.
+
+```cpp
+#include <variant>
+
+std::variant<int, std::string, double> v = 42;
+
+// Check and access
+if (std::holds_alternative<int>(v)) {
+    int i = std::get<int>(v);
+}
+
+// Visitor pattern
+std::visit([](const auto& val) {
+    std::cout << val << '\n';
+}, v);
+
+// Overload helper (C++17 doesn't have std::visit overload; use this pattern)
+template <class... Ts> struct overload : Ts... { using Ts::operator()...; };
+template <class... Ts> overload(Ts...) -> overload<Ts...>;
+
+std::visit(overload{
+    [](int i) { std::cout << "int: " << i << '\n'; },
+    [](const std::string& s) { std::cout << "string: " << s << '\n'; },
+    [](double d) { std::cout << "double: " << d << '\n'; }
+}, v);
+```
+
+## `std::any` (C++17)
+
+Holds any single value of any type. Use when the set of possible types is open-ended.
+
+```cpp
+#include <any>
+
+std::any a = 42;
+a = std::string("hello");
+a = 3.14;
+
+if (a.type() == typeid(double)) {
+    double d = std::any_cast<double>(a);
+}
+
+// Safer: check before cast
+if (auto* pd = std::any_cast<double>(&a)) {
+    std::cout << *pd << '\n';
+}
+```
+
+## Ranges (C++20)
+
+```cpp
+#include <ranges>
+#include <algorithm>
+
+std::vector<int> v = {1, 2, 3, 4, 5, 6};
+
+// Filter and transform lazily — no new vector allocation
+auto evens = v | std::views::filter([](int x) { return x % 2 == 0; });
+auto doubled = evens | std::views::transform([](int x) { return x * 2; });
+
+for (int x : doubled) std::cout << x << ' ';  // 4 8 12
+
+// Range-based sort (C++20 — simpler than iterators)
+std::ranges::sort(v);
+
+// Find
+auto it = std::ranges::find(v, 3);
+
+// All / any / none
+bool has_negative = std::ranges::any_of(v, [](int x) { return x < 0; });
+
+// Projections — sort by member without lambda boilerplate
+struct Employee { std::string name; int level; };
+std::vector<Employee> emps{{"Bob", 3}, {"Alice", 1}, {"Carol", 2}};
+std::ranges::sort(emps, {}, &Employee::level);  // sort by .level
+```
+
+## Concepts (C++20)
+
+Explicit, named constraints on template parameters. Replace SFINAE with readable syntax.
+
+```cpp
+#include <concepts>
+#include <type_traits>
+
+// Define a concept
+template <typename T>
+concept Numeric = std::integral<T> || std::floating_point<T>;
+
+// Use in template parameters
+template <Numeric T>
+T add(T a, T b) { return a + b; }
+
+static_assert(add(1, 2) == 3);
+static_assert(add(1.5, 2.5) == 4.0);
+// add("a", "b") — fails to instantiate: const char* is not Numeric
+
+// Built-in concepts
+static_assert(std::ranges::range<std::vector<int>>);
+static_assert(std::copyable<int>);
+
+// Combining concepts
+template <typename T>
+concept Comparable = requires(T a, T b) {
+    { a < b } -> std::convertible_to<bool>;
+    { a == b } -> std::convertible_to<bool>;
+};
+```
+
+## `std::format` (C++20)
+
+Type-safe, Python-style string formatting.
+
+```cpp
+#include <format>
+#include <chrono>
+
+// Instead of printf/sprintf/cout combos
+std::string s = std::format("{} + {} = {}", 1, 2, 3);  // "1 + 2 = 3"
+std::string t = std::format("{:>10}", 42);              // right-aligned, width 10
+std::string u = std::format("{:.2f}", 3.14159);        // "3.14"
+std::string v = std::format("{:02x}", 255);            // "ff"
+
+// Named arguments
+std::cout << std::format("Hello, {name}! You are {age} years old.\n",
+                         std::format_args::arg("name", "Alice"), /* arg */);
+```
+
+## `std::span` (C++20)
+
+Non-owning view into a contiguous sequence — replacement for pointer+length pairs.
+
+```cpp
+#include <span>
+
+// Instead of (T* ptr, size_t count)
+void print_all(std::span<const int> data) {
+    for (int x : data) std::cout << x << ' ';
+}
+
+std::vector<int> vec{1, 2, 3};
+std::array<int, 3> arr{4, 5, 6};
+int raw[] = {7, 8, 9};
+
+print_all(vec);   // works
+print_all(arr);  // works
+print_all(raw);  // works — decays to span<int, 3>
+print_all({raw, 2});  // explicit length
+```
+
+## `[[likely]]` / `[[unlikely]]` (C++20)
+
+Branch prediction hints for performance-critical paths.
+
+```cpp
+bool process(int x) {
+    if (x > 0) [[likely]] {
+        // compiler may rearrange code for the common case
+        return do_positive(x);
+    }
+    [[unlikely]] {
+        return do_non_positive(x);
+    }
+}
+```

package/.claude/skills/cpp-coding-standards/references/review-checklist.md

@@ -0,0 +1,96 @@
+# C++ Code Review Checklist
+
+Use this checklist when reviewing C++ pull requests or before committing.
+
+## Memory Safety
+
+- [ ] No raw `new` or `delete` — use `std::unique_ptr` / `std::make_unique`
+- [ ] No owning raw pointers as class members (prefer `std::unique_ptr`)
+- [ ] Shared ownership genuinely needed? Consider if `unique_ptr` suffices
+- [ ] `shared_ptr` cycles broken with `weak_ptr`?
+- [ ] Virtual destructor declared on any polymorphic base class
+- [ ] All special member functions (Rule of Five) declared if needed
+- [ ] No use-after-free: references/pointers outlive the data they refer to
+- [ ] Arrays allocated with `new Type[n]` are `delete[]`d (or better, use `vector`)
+
+## RAII and Resource Management
+
+- [ ] File handles, mutexes, sockets use RAII wrappers (destructor cleans up)
+- [ ] `std::lock_guard` / `std::scoped_lock` used for mutex locking — not raw `.lock()/.unlock()`
+- [ ] Every `std::thread` has `.join()` or `.detach()` called before destruction
+- [ ] Prefer `std::jthread` (C++20) for automatic stop and join
+
+## Const Correctness
+
+- [ ] Member functions that don't modify state are marked `const`
+- [ ] Non-modifying parameters passed by `const&` (or by value if cheap-to-copy)
+- [ ] `const` variables used where data doesn't change after init
+- [ ] `const_iterator` used when iteration doesn't modify
+
+## Modern C++ Usage
+
+- [ ] Uses C++17/20 features where appropriate (structured bindings, `if constexpr`, `std::optional`, `string_view`)
+- [ ] No C-style casts — uses `static_cast`, `reinterpret_cast`, `const_cast`
+- [ ] `[[nodiscard]]` on functions returning values that must not be ignored
+- [ ] `override` used on all virtual method overrides
+- [ ] `noexcept` used correctly (only on functions that truly cannot throw)
+- [ ] `std::make_unique` / `std::make_shared` used instead of direct `new`
+
+## Headers and Includes
+
+- [ ] No `using namespace std;` in header files
+- [ ] No unused `#include` directives
+- [ ] Include order: related header first, then standard library, then external libs
+- [ ] Header is self-contained (includes everything it uses)
+
+## Containers and Types
+
+- [ ] `std::vector` preferred over raw arrays for dynamic sequences
+- [ ] `std::vector::reserve()` called when size is known ahead of time
+- [ ] `std::array` used for fixed-size compile-time-known arrays
+- [ ] `std::string_view` used for read-only string params (no ownership)
+- [ ] `std::optional` used instead of sentinel values (e.g., `-1`, `nullptr`) for optional values
+- [ ] No `std::endl` in hot paths (flushes the stream)
+
+## Error Handling
+
+- [ ] Expected failures (not found, invalid input) handled without exceptions
+- [ ] Exceptions used only for truly exceptional/unrecoverable conditions
+- [ ] No exception thrown from destructors (use `noexcept` and `std::terminate` instead if needed)
+- [ ] Exception safety level appropriate for the function (at minimum: no resource leaks)
+- [ ] `std::expected<T, E>` (C++23) or error codes used in library/API code
+
+## Concurrency
+
+- [ ] Shared mutable state protected by `std::mutex` / `std::lock_guard`
+- [ ] No data races on shared variables
+- [ ] `std::atomic` used for simple shared counters and flags
+- [ ] Thread lifecycle managed correctly (`join()`/`detach()` or `jthread`)
+- [ ] No passing of references to locals into detached threads
+
+## Performance Considerations
+
+- [ ] No unnecessary copies (pass by `const&`, use `std::move`, prefer move over copy)
+- [ ] No hidden allocations in hot paths (e.g., `s + "text"` inside a loop)
+- [ ] Vector `reserve()` before known-size loops
+- [ ] Emplacement used when inserting into containers: `vec.emplace_back(args...)` over `vec.push_back(Type(args...))`
+
+## Initialization
+
+- [ ] All variables initialized before use
+- [ ] Member variables initialized in initializer list or with default member initializers
+- [ ] No use of default-initialized built-in types without assignment
+
+## Code Quality
+
+- [ ] No `goto` statements
+- [ ] No macros for anything that can be a `constexpr`, `inline`, or template
+- [ ] Template code in headers uses explicit `typename T` or `class T`
+- [ ] No hardcoded magic numbers — use named constants or `constexpr`
+- [ ] `auto` used appropriately (not hiding intent)
+
+## Testing
+
+- [ ] New code has corresponding unit tests
+- [ ] Edge cases covered: empty containers, zero/negative values, boundary conditions
+- [ ] No commented-out test code committed

package/.claude/skills/cpp-testing/README.md

@@ -0,0 +1,28 @@
+# C++ Testing Skill
+
+C++ testing patterns for Claude Code. Covers unit, integration, and host-side tests, framework selection (GoogleTest / Catch2 / doctest), mocking strategies, TDD workflow, and the 80% coverage gate.
+
+## What it provides
+
+- **SKILL.md** — framework selection + 5 deep-dive references
+- **references/framework-compare.md** — GoogleTest vs Catch2 vs doctest with code samples
+- **references/host-test-for-embedded.md** — pure-CMake host test for firmware `.cpp` without `idf.py`/FreeRTOS
+- **references/mocking.md** — abstract interfaces, link-time seam, `std::function` injection, gmock
+- **references/tdd-workflow.md** — red-green-refactor in C++
+- **references/coverage.md** — gcov/lcov, 80% gate on `main/` and `components/`
+
+## When it triggers
+
+- Writing a new C++ unit or host test
+- Choosing a test framework
+- Setting up a host-side test binary that links firmware code without ESP-IDF
+- Running a test-gate before merging
+- Applying TDD to firmware policy/payload modules
+
+## Manual install
+
+```bash
+cp -R SKILL.md references ~/.claude/skills/cpp-testing/
+```
+
+The BizarHarness installer can also install this automatically — select the **C++ testing** component.