red64-cli 0.5.0 → 0.6.0

package/framework/stacks/cpp/conventions.md

@@ -0,0 +1,420 @@
+# Development Conventions
+
+General development practices, workflow, and operational standards for C++ projects.
+
+---
+
+## Philosophy
+
+- **Predictable process**: Consistent workflows reduce friction and errors
+- **Automated enforcement**: clang-tidy and CI catch what humans miss
+- **Build reproducibility**: Lock dependencies, pin toolchains, use presets
+- **Documentation as code**: Keep docs next to the code they describe
+
+---
+
+## Git Workflow
+
+### Branch Strategy
+
+```
+main              # Production-ready, always builds
+  |-- feat/...    # Feature branches (short-lived)
+  |-- fix/...     # Bug fix branches
+  |-- chore/...   # Maintenance, dependency updates
+```
+
+### Branch Naming
+
+```bash
+feat/add-user-authentication
+fix/buffer-overflow-in-parser
+chore/upgrade-fmt-to-11
+refactor/extract-http-client
+```
+
+**Pattern**: `{type}/{short-description}` with lowercase and hyphens.
+
+### Workflow
+
+1. Create branch from `main`
+2. Make small, focused commits
+3. Open PR when ready for review
+4. Squash merge into `main`
+5. Delete branch after merge
+
+---
+
+## Commit Conventions
+
+### Conventional Commits
+
+```
+feat: add JWT authentication middleware
+fix: prevent buffer overflow in JSON parser
+refactor: extract HTTP client into separate library
+test: add parameterized tests for email validation
+docs: update CMake build instructions
+chore: upgrade vcpkg baseline to 2025.01
+ci: add ASan/UBSan to test matrix
+perf: use string_view to avoid copies in request parsing
+```
+
+### Format
+
+```
+{type}: {short description}
+
+{optional body explaining why, not what}
+
+{optional footer: BREAKING CHANGE, Closes #123}
+```
+
+### Types
+
+| Type | Description |
+|---|---|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `refactor` | Code change that neither fixes nor adds |
+| `test` | Adding or updating tests |
+| `docs` | Documentation only |
+| `chore` | Maintenance, dependencies, tooling |
+| `ci` | CI/CD configuration changes |
+| `perf` | Performance improvement |
+
+**Rule**: One logical change per commit. If the commit message needs "and", split it.
+
+---
+
+## CMake Project Structure
+
+### Standard Layout
+
+```
+myproject/
+  CMakeLists.txt              # Root CMakeLists
+  CMakePresets.json            # Build presets
+  vcpkg.json                   # Dependency manifest
+  .clang-format                # Formatting config
+  .clang-tidy                  # Static analysis config
+  cmake/
+    CompilerWarnings.cmake     # Shared warning flags
+    Sanitizers.cmake           # Sanitizer build options
+  include/
+    myproject/                 # Public headers
+      user_service.hpp
+      http_client.hpp
+  src/
+    user_service.cpp
+    http_client.cpp
+    main.cpp
+  tests/
+    CMakeLists.txt
+    unit/
+      test_user_service.cpp
+    integration/
+      test_database.cpp
+    benchmark/
+      bench_serialization.cpp
+  docs/
+  third_party/                 # Vendored dependencies (if any)
+```
+
+### CMakePresets.json
+
+```json
+{
+    "version": 6,
+    "configurePresets": [
+        {
+            "name": "default",
+            "binaryDir": "${sourceDir}/build",
+            "generator": "Ninja",
+            "cacheVariables": {
+                "CMAKE_CXX_STANDARD": "23",
+                "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
+            },
+            "toolchainFile": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
+        },
+        {
+            "name": "debug",
+            "inherits": "default",
+            "cacheVariables": {
+                "CMAKE_BUILD_TYPE": "Debug"
+            }
+        },
+        {
+            "name": "release",
+            "inherits": "default",
+            "cacheVariables": {
+                "CMAKE_BUILD_TYPE": "Release"
+            }
+        },
+        {
+            "name": "asan",
+            "inherits": "debug",
+            "cacheVariables": {
+                "CMAKE_CXX_FLAGS": "-fsanitize=address,undefined -fno-omit-frame-pointer"
+            }
+        }
+    ],
+    "buildPresets": [
+        {"name": "default", "configurePreset": "default"},
+        {"name": "release", "configurePreset": "release"},
+        {"name": "asan", "configurePreset": "asan"}
+    ],
+    "testPresets": [
+        {
+            "name": "default",
+            "configurePreset": "default",
+            "output": {"outputOnFailure": true}
+        }
+    ]
+}
+```
+
+---
+
+## Dependency Management
+
+### vcpkg Manifest Mode (Preferred)
+
+```json
+{
+    "name": "myproject",
+    "version-string": "1.0.0",
+    "dependencies": [
+        "fmt",
+        "spdlog",
+        "nlohmann-json",
+        "gtest",
+        "benchmark"
+    ],
+    "builtin-baseline": "a1a1cbc975e450accd1f5b7e4530e1378575f291"
+}
+```
+
+```bash
+# Add a dependency
+vcpkg add port abseil
+
+# Update baseline (all dependencies)
+vcpkg x-update-baseline
+```
+
+### Dependency Rules
+
+- Use manifest mode (`vcpkg.json`), not classic mode
+- Pin the baseline hash in `vcpkg.json`
+- Update baseline regularly (monthly or per sprint)
+- Prefer header-only libraries when performance permits
+- Vendor critical dependencies only as a last resort
+
+---
+
+## Header vs Source Organization
+
+### Public vs Private Headers
+
+```
+include/myproject/       # Public API headers (installed with library)
+  user_service.hpp       # Declarations only, minimal includes
+src/
+  user_service.cpp       # Implementations
+  internal/              # Private headers (not installed)
+    database_impl.hpp
+```
+
+### Include Guard Style
+
+```cpp
+// GOOD: #pragma once (widely supported, no name collisions)
+#pragma once
+
+#include <string>
+#include <vector>
+
+namespace myproject {
+class UserService { /* ... */ };
+}  // namespace myproject
+```
+
+```cpp
+// ACCEPTABLE: Traditional include guards (required for some compilers)
+#ifndef MYPROJECT_USER_SERVICE_HPP
+#define MYPROJECT_USER_SERVICE_HPP
+
+// ...
+
+#endif  // MYPROJECT_USER_SERVICE_HPP
+```
+
+**Preference**: Use `#pragma once` unless the project must support exotic compilers.
+
+### Include Order
+
+```cpp
+// 1. Corresponding header (for .cpp files)
+#include "myproject/user_service.hpp"
+
+// 2. C++ standard library
+#include <algorithm>
+#include <string>
+#include <vector>
+
+// 3. Third-party libraries
+#include <fmt/core.h>
+#include <spdlog/spdlog.h>
+#include <nlohmann/json.hpp>
+
+// 4. Project headers
+#include "myproject/database.hpp"
+#include "myproject/error.hpp"
+```
+
+---
+
+## Logging with spdlog
+
+### Setup
+
+```cpp
+#include <spdlog/spdlog.h>
+#include <spdlog/sinks/stdout_color_sinks.h>
+#include <spdlog/sinks/rotating_file_sink.h>
+
+void init_logging() {
+    auto console = std::make_shared<spdlog::sinks::stdout_color_sink_mt>();
+    auto file = std::make_shared<spdlog::sinks::rotating_file_sink_mt>(
+        "logs/app.log", 1024 * 1024 * 5, 3);
+
+    auto logger = std::make_shared<spdlog::logger>(
+        "app", spdlog::sinks_init_list{console, file});
+    logger->set_level(spdlog::level::info);
+    logger->set_pattern("[%Y-%m-%d %H:%M:%S.%e] [%^%l%$] [%t] %v");
+    spdlog::set_default_logger(logger);
+}
+```
+
+### Usage
+
+```cpp
+// GOOD: Structured key-value logging with fmt syntax
+spdlog::info("user_created id={} email={}", user.id(), user.email());
+spdlog::warn("retry_attempt service={} attempt={}/{}", "payment", attempt, max);
+spdlog::error("operation_failed reason={}", error.message());
+
+// BAD: Unstructured string concatenation
+spdlog::info("User " + name + " was created");
+```
+
+### Log Levels
+
+| Level | Use Case |
+|---|---|
+| `trace` | Fine-grained debug detail (disabled in production) |
+| `debug` | Development diagnostics |
+| `info` | Normal operations (request handled, service started) |
+| `warn` | Recoverable issues (retry succeeded, deprecated usage) |
+| `error` | Failed operations (connection lost, invalid response) |
+| `critical` | System unusable (out of memory, data corruption) |
+
+---
+
+## Documentation Standards
+
+### Doxygen-Style Comments
+
+```cpp
+/// @brief Create a new user account.
+///
+/// Validates email uniqueness and hashes the password before
+/// persisting to the database.
+///
+/// @param request Validated user creation request.
+/// @return The created User, or an error if email is taken.
+/// @see UserRepo::save
+[[nodiscard]] Result<User> create_user(const CreateRequest& request);
+```
+
+### When to Write Documentation
+
+| Element | Documentation Required? |
+|---|---|
+| Public class | Yes |
+| Public function/method | Yes |
+| Private function | Only if non-obvious |
+| Test functions | No (test name is the doc) |
+| Template parameters | Yes, describe constraints |
+
+### Inline Comments
+
+```cpp
+// GOOD: Explain WHY, not what
+// Rate limit to 5/min to prevent brute force attacks
+constexpr int kMaxAuthAttemptsPerMinute = 5;
+
+// BAD: Restates the code
+// Set max to 5
+constexpr int kMax = 5;
+```
+
+---
+
+## PR Review Checklist
+
+### Author Checklist (Before Requesting Review)
+
+- [ ] Tests pass locally (`ctest --test-dir build`)
+- [ ] clang-tidy passes (`run-clang-tidy -p build`)
+- [ ] clang-format applied (`clang-format -i ...`)
+- [ ] No compiler warnings with `-Wall -Wextra -Werror`
+- [ ] New features have tests
+- [ ] No secrets or credentials committed
+- [ ] PR description explains WHY, not just what
+
+### Reviewer Checklist
+
+- [ ] Code follows project conventions
+- [ ] Error cases are handled (expected/exceptions)
+- [ ] No raw owning pointers, manual new/delete
+- [ ] No unnecessary copies (use references, string_view, span)
+- [ ] Thread safety considered for shared data
+- [ ] Tests cover happy path and edge cases
+
+---
+
+## .gitignore
+
+```gitignore
+# Build artifacts
+build/
+build-*/
+out/
+
+# IDE
+.vscode/settings.json
+.idea/
+*.swp
+*~
+
+# vcpkg
+vcpkg_installed/
+
+# Coverage
+*.gcda
+*.gcno
+coverage-report/
+
+# Compiled objects
+*.o
+*.obj
+*.a
+*.so
+*.dylib
+```
+
+---
+
+_Conventions reduce cognitive load. Follow them consistently so the team can focus on solving problems, not debating style._

package/framework/stacks/cpp/error-handling.md

@@ -0,0 +1,264 @@
+# Error Handling Patterns
+
+Structured error handling for modern C++ with std::expected (C++23), exceptions, and RAII.
+
+---
+
+## Philosophy
+
+- **Fail fast**: Validate inputs early, return errors immediately on invalid state
+- **Make errors visible**: Use types that force callers to handle failure
+- **RAII for cleanup**: Never write manual cleanup code; destructors handle it
+- **Pick one strategy per layer**: Do not mix exceptions and error codes in the same API surface
+- **Ref**: C++ Core Guidelines E.1-E.31
+
+---
+
+## Exception Safety Guarantees
+
+Every function provides one of these guarantees. Document which one.
+
+| Guarantee | Description | Example |
+|---|---|---|
+| **Nothrow** | Never throws. Marked `noexcept`. | Destructors, swap, move operations |
+| **Strong** | If an exception is thrown, state rolls back to before the call. | Copy-and-swap idiom |
+| **Basic** | If an exception is thrown, no resources leak and invariants hold. Objects may be in a valid but unspecified state. | Most standard library operations |
+
+```cpp
+// Nothrow guarantee: destructors, move operations (CG: C.66, C.85)
+class Connection {
+public:
+    ~Connection() noexcept;
+    Connection(Connection&& other) noexcept;
+    Connection& operator=(Connection&& other) noexcept;
+};
+
+// Strong guarantee via copy-and-swap (CG: C.83)
+class UserList {
+public:
+    UserList& operator=(UserList other) noexcept {  // Pass by value = copy
+        swap(*this, other);                          // noexcept swap
+        return *this;
+    }
+
+    friend void swap(UserList& a, UserList& b) noexcept {
+        using std::swap;
+        swap(a.users_, b.users_);
+    }
+
+private:
+    std::vector<User> users_;
+};
+```
+
+---
+
+## std::expected (C++23) -- Preferred for Recoverable Errors
+
+`std::expected<T, E>` returns either a value of type `T` or an error of type `E`. No stack unwinding, no hidden control flow.
+
+### Error Type Definition
+
+```cpp
+// error.hpp
+#include <string>
+#include <expected>
+
+enum class ErrorCode {
+    kNotFound,
+    kAlreadyExists,
+    kUnauthorized,
+    kValidation,
+    kInternal,
+    kTimeout,
+};
+
+struct Error {
+    ErrorCode code;
+    std::string message;
+    std::string context;  // Optional: file, function, etc.
+};
+
+template <typename T>
+using Result = std::expected<T, Error>;
+```
+
+### Basic Usage
+
+```cpp
+Result<User> find_user(int user_id) {
+    auto row = db_.query_one("SELECT * FROM users WHERE id = ?", user_id);
+    if (!row) {
+        return std::unexpected(Error{
+            .code = ErrorCode::kNotFound,
+            .message = fmt::format("User {} not found", user_id),
+        });
+    }
+    return User::from_row(*row);
+}
+
+// Caller
+auto result = find_user(42);
+if (result) {
+    spdlog::info("Found user: {}", result->name());
+} else {
+    spdlog::warn("Error: {}", result.error().message);
+}
+```
+
+### Monadic Chaining (C++23)
+
+```cpp
+// Chain operations that may fail: and_then, transform, or_else
+auto user = find_user(user_id)
+    .and_then([](User u) -> Result<User> {
+        if (!u.is_active()) {
+            return std::unexpected(Error{ErrorCode::kUnauthorized, "User inactive"});
+        }
+        return u;
+    })
+    .transform([](User u) {
+        return UserResponse{u.name(), u.email()};
+    });
+```
+
+### Pre-C++23 Alternative: tl::expected
+
+```cpp
+// Use tl::expected if your compiler does not yet support std::expected
+#include <tl/expected.hpp>
+
+template <typename T>
+using Result = tl::expected<T, Error>;
+```
+
+---
+
+## When to Use Each Error Strategy
+
+| Strategy | Use Case | Example |
+|---|---|---|
+| **std::expected** | Recoverable, expected failures | File not found, validation, business logic |
+| **Exceptions** | Unrecoverable or truly exceptional errors | Out of memory, corrupted state, programmer error |
+| **Error codes (enum)** | C interop, embedded, real-time, no-exception builds | OS APIs, hardware drivers |
+| **std::optional** | "No value" without error details | Cache miss, optional config lookup |
+| **assert / contracts** | Precondition violations in debug builds | `assert(ptr != nullptr)` |
+
+### Exceptions: When Appropriate (CG: E.2, E.3)
+
+```cpp
+// GOOD: Exception for constructor failure (no return value to use)
+class DatabaseConnection {
+public:
+    explicit DatabaseConnection(std::string_view conn_str) {
+        handle_ = connect(conn_str);
+        if (!handle_) {
+            throw std::runtime_error(
+                fmt::format("Failed to connect to database: {}", conn_str));
+        }
+    }
+private:
+    ConnectionHandle handle_;
+};
+
+// GOOD: Exception for programming errors (should not happen in correct code)
+void process(std::span<const int> data) {
+    if (data.empty()) {
+        throw std::invalid_argument("data must not be empty");
+    }
+}
+```
+
+---
+
+## RAII for Cleanup (CG: R.1)
+
+```cpp
+// GOOD: RAII handles all cleanup automatically
+void transfer_funds(Account& from, Account& to, int amount) {
+    auto transaction = db_.begin_transaction();  // RAII: auto-rollback on exception
+
+    from.withdraw(amount);
+    to.deposit(amount);
+
+    transaction.commit();  // Explicit commit; destructor rolls back if not called
+}
+
+// BAD: Manual cleanup -- exception-unsafe
+void transfer_funds_bad(Account& from, Account& to, int amount) {
+    auto* txn = db_.begin_transaction_raw();
+    from.withdraw(amount);   // If this throws, txn is leaked
+    to.deposit(amount);
+    txn->commit();
+    delete txn;              // Never reached on exception
+}
+```
+
+---
+
+## noexcept Specification (CG: E.12)
+
+```cpp
+// GOOD: Mark functions noexcept when they genuinely cannot throw
+void swap(Buffer& other) noexcept;
+Buffer(Buffer&& other) noexcept;
+~Buffer() noexcept;  // Destructors are implicitly noexcept
+
+// GOOD: Conditional noexcept for templates
+template <typename T>
+void swap(T& a, T& b) noexcept(std::is_nothrow_move_constructible_v<T>);
+
+// BAD: Marking functions noexcept when they might throw
+// If they do throw, std::terminate is called immediately -- no cleanup!
+void parse_config(std::string_view json) noexcept;  // JSON parsing can fail!
+```
+
+---
+
+## Custom Exception Hierarchy (When Using Exceptions)
+
+```cpp
+// Base application exception
+class AppError : public std::runtime_error {
+public:
+    explicit AppError(ErrorCode code, std::string_view message)
+        : std::runtime_error(std::string(message))
+        , code_(code) {}
+
+    [[nodiscard]] ErrorCode code() const noexcept { return code_; }
+
+private:
+    ErrorCode code_;
+};
+
+class NotFoundError : public AppError {
+public:
+    NotFoundError(std::string_view resource, std::string_view id)
+        : AppError(ErrorCode::kNotFound,
+                   fmt::format("{} not found: {}", resource, id)) {}
+};
+
+class ValidationError : public AppError {
+public:
+    explicit ValidationError(std::string_view message)
+        : AppError(ErrorCode::kValidation, message) {}
+};
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Correct Approach |
+|---|---|---|
+| `catch (...)` with no rethrow | Silently swallows all errors including memory corruption | Catch specific types; rethrow unknown |
+| Catching by value | Slices derived exceptions, copies unnecessarily | Catch by `const` reference: `catch (const Error& e)` |
+| Bare `throw;` in wrong context | UB if no active exception | Only use `throw;` inside a catch block |
+| Ignoring return codes | Missed errors propagate silently | Use `[[nodiscard]]` on error-returning functions |
+| Manual cleanup without RAII | Exception-unsafe, leak-prone | Wrap resources in RAII types |
+| `noexcept` on functions that throw | Calls `std::terminate` with no stack unwinding | Only mark truly non-throwing functions |
+| Using error codes where expected fits | Verbose, easy to ignore | Use `std::expected<T, E>` for typed results |
+
+---
+
+_Errors are data. Classify them, make them visible in the type system, and let RAII handle cleanup. Never swallow errors silently._