[PR #2] [MERGED] feat: add production-ready features with async logging, security, and Rich output #81

New issue

Closed

opened 2026-02-27 10:22:08 +03:00 by kerem · 0 comments

kerem commented

2026-02-27 10:22:08 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/mikeyobrien/ralph-orchestrator/pull/2
Author: @mikeyobrien
Created: 12/13/2025
Status: ✅ Merged
Merged: 12/13/2025
Merged by: @mikeyobrien

Base: main ← Head: fix/async-logger-thread-safety

📝 Commits (10+)

9f48831 chore: clean up development artifacts for GA release
c20e4d5 docs: mark GA cleanup task complete with validation
94f96f0 docs: final verification of GA release cleanup
905be96 feat: add SecurityValidator system for input validation and path sanitization
bfe3c73 feat: add thread-safe configuration with ConfigValidator
38fb0bd feat: add advanced async logging with rotation and security masking
f3e59c8 feat: implement graceful signal handling with subprocess-first cleanup
bf94f5f feat: add error formatter with user-friendly suggestions
b54b7df feat: add VerboseLogger with session metrics and Rich integration
6a82c1d feat: add memory-efficient IterationStats for per-iteration tracking

📊 Changes

43 files changed (+11998 additions, -946 deletions)

View changed files

📝 .gitignore (+2 -0)
➖ CLAUDE_TOOLS_UPDATE.md (+0 -141)
📝 PROMPT.md (+285 -118)
📝 README.md (+45 -13)
➖ mkdocs-simple.yml (+0 -66)
📝 pyproject.toml (+2 -0)
➖ ralph-orchestrator/docs/api/orchestrator.md (+0 -0)
📝 src/ralph_orchestrator/__init__.py (+16 -2)
📝 src/ralph_orchestrator/__main__.py (+144 -104)
📝 src/ralph_orchestrator/adapters/claude.py (+230 -106)
📝 src/ralph_orchestrator/adapters/qchat.py (+11 -9)
➕ src/ralph_orchestrator/async_logger.py (+472 -0)
📝 src/ralph_orchestrator/context.py (+44 -14)
➕ src/ralph_orchestrator/error_formatter.py (+235 -0)
📝 src/ralph_orchestrator/logging_config.py (+7 -3)
📝 src/ralph_orchestrator/main.py (+340 -17)
📝 src/ralph_orchestrator/metrics.py (+173 -2)
📝 src/ralph_orchestrator/orchestrator.py (+197 -66)
➕ src/ralph_orchestrator/output/__init__.py (+121 -0)
➕ src/ralph_orchestrator/output/base.py (+404 -0)

...and 23 more files

📄 Description

Summary

This PR adds multiple production-ready features to ralph-orchestrator, bringing it from MVP to GA quality.

New Modules

Module	Purpose
`async_logger.py`	Advanced async logging with rotation & security masking
`error_formatter.py`	User-friendly error messages with actionable suggestions
`security.py`	Input validation & path sanitization (SecurityValidator)
`verbose_logger.py`	Session metrics with Rich integration
`output.py`	Rich-based console output with diff formatting
`output_formatter.py`	Smart content detection & formatting for Claude adapter responses

Enhanced Modules

Module	Enhancement
`metrics.py`	Added `IterationStats` for memory-efficient per-iteration tracking
`main.py`	Added thread-safe `ConfigValidator` with validation warnings
`orchestrator.py`	Graceful signal handling with subprocess-first cleanup
`adapters/claude.py`	Cache dir init, tool_permissions, RalphConsole integration
`context.py`	Added `prompt_text` support for inline prompts

New Features

Inline prompt support: Pass prompts directly via -p/--prompt-text flag instead of requiring a file
- -p "Build a REST API" for inline text
- -P task.md for file path (renamed from -p)
Smart output formatting: RichTerminalFormatter with content-type detection for code blocks, diffs, errors, and plain text
RalphConsole integration: ClaudeAdapter uses Rich-based console for formatted output

Bug Fixes

async_logger thread-safety: Fixed deadlock in sync methods when called from multiple threads (asyncio.Lock is not thread-safe across event loops)
Debug logging in silent handlers: Added debug logging to silent exception handlers for troubleshooting
Test stderr mock: Fixed incorrect mock in test_sync_logging_handles_stderr_failure_silently
Graceful Ctrl-C handling: SIGINT now logs INFO instead of ERROR with traceback
Corrected logging levels: 18 logging statements fixed across codebase:
- ERROR → WARNING for handled/expected failures (timeouts, process kills, non-zero returns)
- WARNING → INFO for normal operations (safety limits, state resets, missing files)

Commits

a672f50 fix: correct logging levels across codebase
f0722a8 fix: address PR review issues
81ab98c fix: correct stderr mock in test_sync_logging_handles_stderr_failure_silently
c6d647d fix: add debug logging to silent exception handlers and improve tests
dab9a27 feat: integrate RalphConsole for rich output formatting in ClaudeAdapter
4f66180 feat: add smart content detection to RichTerminalFormatter
cbe5e6b test: improve output formatter test coverage to 96%
6586eb2 feat: add output formatter module for Claude adapter responses
a11fcdb fix: improve error handling and add thread-safety regression tests
ada8b7c feat: add inline prompt support via -p/--prompt-text CLI flag
e5577bb fix: resolve asyncio Lock thread-safety deadlock in sync methods
6224639 feat: add Rich-based output module with enhanced console output
762dafe Complete verification checklist - all items verified
5c49dde fix: add cache dir to init and tool_permissions to AdapterConfig
6a82c1d feat: add memory-efficient IterationStats for per-iteration tracking
b54b7df feat: add VerboseLogger with session metrics and Rich integration
bf94f5f feat: add error formatter with user-friendly suggestions
f3e59c8 feat: implement graceful signal handling with subprocess-first cleanup
38fb0bd feat: add advanced async logging with rotation and security masking
bfe3c73 feat: add thread-safe configuration with ConfigValidator
905be96 feat: add SecurityValidator system for input validation and path sanitization
94f96f0 docs: final verification of GA release cleanup
c20e4d5 docs: mark GA cleanup task complete with validation
9f48831 chore: clean up development artifacts for GA release

Test plan

309+ core module tests pass
All new modules have comprehensive test coverage
Output formatter test coverage at 96%
Thread-safety regression tests added
Fixed hanging test_concurrent_sync_logging test
New test_context.py for prompt_text feature
New test for SIGINT cancellation handling

🤖 Generated with Claude Code

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/mikeyobrien/ralph-orchestrator/pull/2 **Author:** [@mikeyobrien](https://github.com/mikeyobrien) **Created:** 12/13/2025 **Status:** ✅ Merged **Merged:** 12/13/2025 **Merged by:** [@mikeyobrien](https://github.com/mikeyobrien) **Base:** `main` ← **Head:** `fix/async-logger-thread-safety` --- ### 📝 Commits (10+) - [`9f48831`](https://github.com/mikeyobrien/ralph-orchestrator/commit/9f4883192fb8e060fce0c221b62421c2c06ce6d5) chore: clean up development artifacts for GA release - [`c20e4d5`](https://github.com/mikeyobrien/ralph-orchestrator/commit/c20e4d5062dfa1d9eeabb4ef5a47a0c860428d6e) docs: mark GA cleanup task complete with validation - [`94f96f0`](https://github.com/mikeyobrien/ralph-orchestrator/commit/94f96f055e75daef740291011273cfb42212382d) docs: final verification of GA release cleanup - [`905be96`](https://github.com/mikeyobrien/ralph-orchestrator/commit/905be96530ca25d62d71fadb64794075f036e90e) feat: add SecurityValidator system for input validation and path sanitization - [`bfe3c73`](https://github.com/mikeyobrien/ralph-orchestrator/commit/bfe3c73bb23324d71ad895ed731b29cd34a01f1e) feat: add thread-safe configuration with ConfigValidator - [`38fb0bd`](https://github.com/mikeyobrien/ralph-orchestrator/commit/38fb0bd5482a0325528e32d11055964b1214576c) feat: add advanced async logging with rotation and security masking - [`f3e59c8`](https://github.com/mikeyobrien/ralph-orchestrator/commit/f3e59c8db863cb809cbcaf6a90552f1efb784fef) feat: implement graceful signal handling with subprocess-first cleanup - [`bf94f5f`](https://github.com/mikeyobrien/ralph-orchestrator/commit/bf94f5f9b4b1ece110fa50ad2c4556a237f64b0b) feat: add error formatter with user-friendly suggestions - [`b54b7df`](https://github.com/mikeyobrien/ralph-orchestrator/commit/b54b7df9736d9b248053c1e93e7272e83fc46f3c) feat: add VerboseLogger with session metrics and Rich integration - [`6a82c1d`](https://github.com/mikeyobrien/ralph-orchestrator/commit/6a82c1d3e34256a156d70f2375fbd009decbc559) feat: add memory-efficient IterationStats for per-iteration tracking ### 📊 Changes **43 files changed** (+11998 additions, -946 deletions) <details> <summary>View changed files</summary> 📝 `.gitignore` (+2 -0) ➖ `CLAUDE_TOOLS_UPDATE.md` (+0 -141) 📝 `PROMPT.md` (+285 -118) 📝 `README.md` (+45 -13) ➖ `mkdocs-simple.yml` (+0 -66) 📝 `pyproject.toml` (+2 -0) ➖ `ralph-orchestrator/docs/api/orchestrator.md` (+0 -0) 📝 `src/ralph_orchestrator/__init__.py` (+16 -2) 📝 `src/ralph_orchestrator/__main__.py` (+144 -104) 📝 `src/ralph_orchestrator/adapters/claude.py` (+230 -106) 📝 `src/ralph_orchestrator/adapters/qchat.py` (+11 -9) ➕ `src/ralph_orchestrator/async_logger.py` (+472 -0) 📝 `src/ralph_orchestrator/context.py` (+44 -14) ➕ `src/ralph_orchestrator/error_formatter.py` (+235 -0) 📝 `src/ralph_orchestrator/logging_config.py` (+7 -3) 📝 `src/ralph_orchestrator/main.py` (+340 -17) 📝 `src/ralph_orchestrator/metrics.py` (+173 -2) 📝 `src/ralph_orchestrator/orchestrator.py` (+197 -66) ➕ `src/ralph_orchestrator/output/__init__.py` (+121 -0) ➕ `src/ralph_orchestrator/output/base.py` (+404 -0) _...and 23 more files_ </details> ### 📄 Description ## Summary This PR adds multiple production-ready features to ralph-orchestrator, bringing it from MVP to GA quality. ## New Modules | Module | Purpose | |--------|---------| | `async_logger.py` | Advanced async logging with rotation & security masking | | `error_formatter.py` | User-friendly error messages with actionable suggestions | | `security.py` | Input validation & path sanitization (SecurityValidator) | | `verbose_logger.py` | Session metrics with Rich integration | | `output.py` | Rich-based console output with diff formatting | | `output_formatter.py` | Smart content detection & formatting for Claude adapter responses | ## Enhanced Modules | Module | Enhancement | |--------|-------------| | `metrics.py` | Added `IterationStats` for memory-efficient per-iteration tracking | | `main.py` | Added thread-safe `ConfigValidator` with validation warnings | | `orchestrator.py` | Graceful signal handling with subprocess-first cleanup | | `adapters/claude.py` | Cache dir init, tool_permissions, RalphConsole integration | | `context.py` | Added `prompt_text` support for inline prompts | ## New Features - **Inline prompt support**: Pass prompts directly via `-p/--prompt-text` flag instead of requiring a file - `-p "Build a REST API"` for inline text - `-P task.md` for file path (renamed from `-p`) - **Smart output formatting**: `RichTerminalFormatter` with content-type detection for code blocks, diffs, errors, and plain text - **RalphConsole integration**: ClaudeAdapter uses Rich-based console for formatted output ## Bug Fixes - **async_logger thread-safety**: Fixed deadlock in sync methods when called from multiple threads (asyncio.Lock is not thread-safe across event loops) - **Debug logging in silent handlers**: Added debug logging to silent exception handlers for troubleshooting - **Test stderr mock**: Fixed incorrect mock in `test_sync_logging_handles_stderr_failure_silently` - **Graceful Ctrl-C handling**: SIGINT now logs INFO instead of ERROR with traceback - **Corrected logging levels**: 18 logging statements fixed across codebase: - ERROR → WARNING for handled/expected failures (timeouts, process kills, non-zero returns) - WARNING → INFO for normal operations (safety limits, state resets, missing files) ## Commits ``` a672f50 fix: correct logging levels across codebase f0722a8 fix: address PR review issues 81ab98c fix: correct stderr mock in test_sync_logging_handles_stderr_failure_silently c6d647d fix: add debug logging to silent exception handlers and improve tests dab9a27 feat: integrate RalphConsole for rich output formatting in ClaudeAdapter 4f66180 feat: add smart content detection to RichTerminalFormatter cbe5e6b test: improve output formatter test coverage to 96% 6586eb2 feat: add output formatter module for Claude adapter responses a11fcdb fix: improve error handling and add thread-safety regression tests ada8b7c feat: add inline prompt support via -p/--prompt-text CLI flag e5577bb fix: resolve asyncio Lock thread-safety deadlock in sync methods 6224639 feat: add Rich-based output module with enhanced console output 762dafe Complete verification checklist - all items verified 5c49dde fix: add cache dir to init and tool_permissions to AdapterConfig 6a82c1d feat: add memory-efficient IterationStats for per-iteration tracking b54b7df feat: add VerboseLogger with session metrics and Rich integration bf94f5f feat: add error formatter with user-friendly suggestions f3e59c8 feat: implement graceful signal handling with subprocess-first cleanup 38fb0bd feat: add advanced async logging with rotation and security masking bfe3c73 feat: add thread-safe configuration with ConfigValidator 905be96 feat: add SecurityValidator system for input validation and path sanitization 94f96f0 docs: final verification of GA release cleanup c20e4d5 docs: mark GA cleanup task complete with validation 9f48831 chore: clean up development artifacts for GA release ``` ## Test plan - [x] 309+ core module tests pass - [x] All new modules have comprehensive test coverage - [x] Output formatter test coverage at 96% - [x] Thread-safety regression tests added - [x] Fixed hanging `test_concurrent_sync_logging` test - [x] New `test_context.py` for prompt_text feature - [x] New test for SIGINT cancellation handling 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>