Initial public release: async structured logger, docs, tests, CI, all meta files

Author: mbn-code

.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install build tools
+      run: sudo apt-get update && sudo apt-get install -y g++ make
+    - name: Build and run tests
+      run: |
+        g++ -std=c++17 -pthread -Iinclude tests/async_flush.cpp -o async_flush
+        ./async_flush
+        g++ -std=c++17 -pthread -Iinclude tests/file_sink.cpp -o file_sink
+        ./file_sink
+        g++ -std=c++17 -pthread -Iinclude tests/sync_mode.cpp -o sync_mode
+        ./sync_mode
+        g++ -std=c++17 -pthread -Iinclude tests/basic.cpp -o basic
+        ./basic

.gitignore

@@ -0,0 +1,31 @@
+.DS_Store
+*.o
+*.obj
+*.exe
+*.out
+*.bin
+*.a
+*.so
+*.dll
+*.log
+*.db
+*.suo
+*.user
+*.userosscache
+*.sln.docstates
+*.swp
+*.dSYM/
+*.vcxproj*
+*.sln
+*.cproj
+build/
+CMakeFiles/
+cmake-build*/
+*.orig
+*.core
+*.tmp
+*.test
+*.t
+.turd*
+__pycache__/
+.env

CHANGELOG.md

@@ -0,0 +1,14 @@
+# cLog Changelog
+
+## [v0.1.0] - 2026-02-10
+### Added
+- First public release: async by default, robust background log draining, JSON output.
+- File/console sink, chainable API for log creation.
+- Test suite for async flush, sync mode, file sink, and crash-avoidance.
+- Modern, minimal, single-header main implementation.
+
+### Fixed
+- Thread shutdown is lossless—background logging thread fully drains before logger destruction.
+
+---
+All changes will be documented in this file.

CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing to cLog
+
+Thank you for your interest in contributing!
+
+## How to Contribute
+1. **Fork the repository** and clone it locally.
+2. **Create a new branch** for each feature or fix.
+3. **Write clear code** and **add tests** for any new behavior.
+4. **Run all tests** (`g++ -std=c++17 -pthread -Iinclude tests/*.cpp && ./...`) before submitting.
+5. **Open a pull request** (PR) with a clear, descriptive title and summary.
+6. **Participate in code review**—be responsive, constructive, and open!
+
+## Reporting Issues
+- Search for existing issues first.
+- Open an Issue with a clear description, steps to reproduce, your platform, and expected vs. actual behavior.
+- Bug reports, documentation, and feature requests all welcome!
+
+## Code Style
+- Modern C++17. Prefer clarity, consistency, and minimal macros.
+- Document any public APIs in comments.
+- Chainable builder APIs and clear naming are preferred.
+
+## License
+By contributing you agree your work will be licensed under the MIT license.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cLog contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,75 @@
+# cLog – Modern C++ Logging Library
+
+> **Frictionless, async-by-default, structured JSON logging for modern C++**
+
+## Quickstart Example
+```cpp
+#include "logger.hpp"
+int main() {
+    Logger log;
+    log.info("system.start").kv("version", "1.0");
+}
+```
+**First log call launches a background worker thread for async output by default.**
+
+---
+
+## Features (Design Table)
+| Feature                 | Approach                                                        |
+|-------------------------|-----------------------------------------------------------------|
+| Installation            | Single header, instant use, nlohmann/json is fully internal      |
+| First Log               | Async by default—first use launches worker thread, documented up front |
+| Sync Mode               | Compile-time build flag for full sync, runtime opt-in if available |
+| No Macros               | Never used—tooling, refactoring, and debugging always work        |
+| Structured Logs         | JSON output, no user-level JSON code                            |
+| Compile-time level      | Minimal overhead when disabled; eliminates dead code             |
+| Sinks                   | Console/file by default; custom/extensible sinks, not required   |
+| Debug/Stack Context     | Opt-in: header, adds stacktrace/thread/context as desired        |
+| Thread Info             | Included via debug header/opt-in only                            |
+| Config                  | (Future) JSON/YAML—deserializes to core logger API, never magic  |
+| Testing/CI              | GoogleTest + GitHub Actions, boring, predictable, cross-platform |
+| Docs/Examples           | Always shows one-liner start, then advanced opt-ins              |
+
+---
+
+## Rationale and Values
+- **Zero-magic API**
+- **No macros ever**: Easy refactoring and debugging
+- **Async by default, never silent**: Docs and behavior preempt confusion
+- **Structured JSON output only**: No user-facing JSON APIs
+- **Extensible, but extensions never required**
+
+For more, see [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) (to be added).
+
+---
+
+## Async and Sync Behavior
+- Async (background thread and queue) is the default. First log output launches async worker.
+- Sync mode: Compile-time flag disables async for embedded/hard-realtime, or use `Logger log(Logger::Mode::Sync);` at runtime where threads are available.
+
+---
+
+## Sinks and Extensibility
+- Output goes to stderr (JSON per line) by default
+- Register file or custom sinks using `.add_sink(std::make_unique<FileSink>("file.log"));`
+- All extensibility is opt-in. No required advanced config.
+
+---
+
+## Debugging, Stack, and Thread Context
+- Include `logger_debug.hpp` to add `.with_stacktrace()`/`.with_context()`/`.with_threadinfo()` to entries.
+- Zero core overhead unless debug features are requested.
+
+---
+
+## FAQ
+- **Q: Do I ever need to touch JSON types?**
+  > Never. JSON is entirely internal.
+
+- **Q: Why async by default?**
+  > For performance. You control opt-out via build or API.
+
+---
+
+## License
+MIT. Includes vendored [nlohmann/json](https://github.com/nlohmann/json) (MIT).

examples/hello

@@ -0,0 +1,10 @@
+#include "../include/logger.hpp"
+
+int main() {
+    c_log::Logger log;
+    log.info("system.start")
+       .kv("version", "1.0")
+       .kv("user_count", 5);
+    // flush current record on destruction
+    return 0;
+}

examples/hello.cpp

@@ -0,0 +1,9 @@
+#include "../include/logger.hpp"
+
+int main() {
+    Logger log; // async by default
+    log.info("app.start").kv("version", "0.1").send();
+    log.error("db.fail").kv("query", "SELECT * FROM foo").kv("code", 10).send();
+    log.set_level(Logger::Level::Warning);
+    log.warn("low.battery").kv("percent", 15).send();
+}