Merge pull request #47 from frankbria/feature/phase-1.1-modern-cli-commands

[P1] feat(cli): add modern CLI commands with JSON output support (Phase 1.1)

Author: frankbria

CLAUDE.md

@@ -30,11 +30,17 @@ The system uses a modular architecture with reusable components in the `lib/` di
 
 2. **lib/response_analyzer.sh** - Intelligent response analysis
    - Analyzes Claude Code output for completion signals
+   - **JSON output format detection and parsing** (with text fallback)
+   - Extracts structured fields: status, exit_signal, work_type, files_modified
    - Detects test-only loops and stuck error patterns
    - Two-stage error filtering to eliminate false positives
    - Multi-line error matching for accurate stuck loop detection
    - Confidence scoring for exit decisions
 
+3. **lib/date_utils.sh** - Cross-platform date utilities
+   - ISO timestamp generation for logging
+   - Epoch time calculations for rate limiting
+
 ## Key Commands
 
 ### Installation
@@ -96,6 +102,35 @@ The loop is controlled by several key files and environment variables:
 - Automatic hourly reset with countdown display
 - Call tracking persists across script restarts
 
+### Modern CLI Configuration (Phase 1.1)
+
+Ralph uses modern Claude Code CLI flags for structured communication:
+
+**Configuration Variables:**
+```bash
+CLAUDE_OUTPUT_FORMAT="json"           # Output format: json (default) or text
+CLAUDE_ALLOWED_TOOLS="Write,Bash(git *),Read"  # Allowed tool permissions
+CLAUDE_USE_CONTINUE=true              # Enable session continuity
+CLAUDE_MIN_VERSION="2.0.76"           # Minimum Claude CLI version
+```
+
+**CLI Options:**
+- `--output-format json|text` - Set Claude output format (default: json)
+- `--allowed-tools "Write,Read,Bash(git *)"` - Restrict allowed tools
+- `--no-continue` - Disable session continuity, start fresh each loop
+
+**Loop Context:**
+Each loop iteration injects context via `build_loop_context()`:
+- Current loop number
+- Remaining tasks from @fix_plan.md
+- Circuit breaker state (if not CLOSED)
+- Previous loop work summary
+
+**Session Continuity:**
+- Sessions are preserved in `.claude_session_id`
+- Use `--continue` flag to maintain context across loops
+- Disable with `--no-continue` for isolated iterations
+
 ### Intelligent Exit Detection
 The loop automatically exits when it detects project completion through:
 - Multiple consecutive "done" signals from Claude Code
@@ -193,6 +228,37 @@ Ralph uses advanced error detection with two-stage filtering to eliminate false
 
 ## Recent Improvements
 
+### Modern CLI Commands (v0.9.1 - Phase 1.1)
+
+**JSON Output Format Support**
+- Added `detect_output_format()` function to identify JSON vs text output
+- Added `parse_json_response()` to extract structured fields from Claude's JSON output
+- Extracts: status, exit_signal, work_type, files_modified, error_count, summary
+- Automatic fallback to text parsing on malformed JSON
+- Maintains backward compatibility with traditional RALPH_STATUS format
+
+**Session Continuity Management**
+- `init_claude_session()` - Resume or start new sessions
+- `save_claude_session()` - Persist session ID from Claude output
+- `--continue` flag for context preservation across loops
+- `--no-continue` option for isolated iterations
+
+**Loop Context Injection**
+- `build_loop_context()` - Build contextual information for each loop
+- Includes: loop number, remaining tasks, circuit breaker state, previous work summary
+- Injected via `--append-system-prompt` for Claude awareness
+
+**Modern CLI Flags**
+- `--output-format json|text` - Control Claude output format
+- `--allowed-tools` - Restrict tool permissions
+- `--prompt-file` - Use file instead of stdin piping
+- Version checking with `check_claude_version()`
+
+**Test Coverage**
+- 20 new JSON parsing tests in `test_json_parsing.bats`
+- 23 new CLI modern tests in `test_cli_modern.bats`
+- All 98 tests passing (100% pass rate)
+
 ### Circuit Breaker Enhancements (v0.9.0)
 
 **Multi-line Error Matching Fix**

README.md

@@ -1,9 +1,9 @@
 # Ralph for Claude Code
 
-![Version](https://img.shields.io/badge/version-0.9.0-blue)
+![Version](https://img.shields.io/badge/version-0.9.1-blue)
 ![Status](https://img.shields.io/badge/status-active%20development-yellow)
-![Tests](https://img.shields.io/badge/tests-75%20passing-green)
-![Coverage](https://img.shields.io/badge/coverage-60%25-orange)
+![Tests](https://img.shields.io/badge/tests-98%20passing-green)
+![Coverage](https://img.shields.io/badge/coverage-65%25-orange)
 
 > **Autonomous AI development loop with intelligent exit detection and rate limiting**
 
@@ -13,23 +13,34 @@ Ralph is an implementation of the Geoffrey Huntley's technique for Claude Code t
 
 ## 📌 Project Status
 
-**Version**: v0.9.0 - Active Development
+**Version**: v0.9.1 - Active Development
 **Core Features**: ✅ Working and tested
-**Test Coverage**: 60% (expanding to 90%+ - see [roadmap](#-development-roadmap))
+**Test Coverage**: 65% (expanding to 90%+ - see [roadmap](#-development-roadmap))
 
 ### What's Working Now ✅
 - Autonomous development loops with intelligent exit detection
 - Rate limiting with hourly reset (100 calls/hour, configurable)
 - Circuit breaker with advanced error detection (prevents runaway loops)
 - Response analyzer with semantic understanding and two-stage error filtering
+- **JSON output format support with automatic fallback to text parsing**
+- **Session continuity with `--continue` flag for context preservation**
+- **Modern CLI flags: `--output-format`, `--allowed-tools`, `--no-continue`**
 - Multi-line error matching for accurate stuck loop detection
 - 5-hour API limit handling with user prompts
 - tmux integration for live monitoring
 - PRD import functionality
-- 97 passing tests covering critical paths (13 error detection + 9 stuck loop + 75 core tests)
+- 98 passing tests covering critical paths (20 JSON parsing + 23 CLI modern + 55 core tests)
 
 ### Recent Improvements 🎉
 
+**v0.9.1 - Modern CLI Commands (Phase 1.1)**
+- ✅ JSON output format support with `--output-format json` (default)
+- ✅ Session continuity using `--continue` flag for cross-loop context
+- ✅ Tool permissions via `--allowed-tools` flag
+- ✅ Loop context injection with `build_loop_context()` function
+- ✅ Backward-compatible: automatic fallback to text parsing
+- ✅ 43 new tests: JSON parsing (20) + CLI modern (23)
+
 **v0.9.0 - Circuit Breaker Enhancements**
 - ✅ Fixed multi-line error matching in stuck loop detection
 - ✅ Eliminated JSON field false positives (e.g., `"is_error": false`)
@@ -339,26 +350,27 @@ If you want to run the test suite:
 # Install BATS testing framework
 npm install -g bats bats-support bats-assert
 
-# Run all tests (97 tests)
+# Run all tests (98 tests)
 bats tests/
 
 # Run specific test suites
 bats tests/unit/test_rate_limiting.bats
 bats tests/unit/test_exit_detection.bats
+bats tests/unit/test_json_parsing.bats
+bats tests/unit/test_cli_modern.bats
 bats tests/integration/test_loop_execution.bats
-bats tests/integration/test_edge_cases.bats
 
 # Run error detection and circuit breaker tests
 ./tests/test_error_detection.sh
 ./tests/test_stuck_loop_detection.sh
 ```
 
 Current test status:
-- **97 tests** across 6 test files (75 core + 13 error detection + 9 stuck loop)
-- **100% pass rate** (97/97 passing)
-- **~60% code coverage** (target: 90%+)
+- **98 tests** across 7 test files (55 core + 20 JSON parsing + 23 CLI modern)
+- **100% pass rate** (98/98 passing)
+- **~65% code coverage** (target: 90%+)
 - Comprehensive unit and integration tests
-- Specialized tests for error detection and circuit breaker functionality
+- Specialized tests for JSON parsing, CLI flags, and circuit breaker functionality
 
 ### Installing tmux
 
@@ -537,13 +549,16 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 ### Ralph Loop Options
 ```bash
 ralph [OPTIONS]
-  -h, --help          Show help message
-  -c, --calls NUM     Set max calls per hour (default: 100)
-  -p, --prompt FILE   Set prompt file (default: PROMPT.md)
-  -s, --status        Show current status and exit
-  -m, --monitor       Start with tmux session and live monitor
-  -v, --verbose       Show detailed progress updates during execution
-  -t, --timeout MIN   Set Claude Code execution timeout in minutes (1-120, default: 15)
+  -h, --help              Show help message
+  -c, --calls NUM         Set max calls per hour (default: 100)
+  -p, --prompt FILE       Set prompt file (default: PROMPT.md)
+  -s, --status            Show current status and exit
+  -m, --monitor           Start with tmux session and live monitor
+  -v, --verbose           Show detailed progress updates during execution
+  -t, --timeout MIN       Set Claude Code execution timeout in minutes (1-120, default: 15)
+  --output-format FORMAT  Set output format: json (default) or text
+  --allowed-tools TOOLS   Set allowed Claude tools (default: Write,Bash(git *),Read)
+  --no-continue           Disable session continuity (start fresh each loop)
 ```
 
 ### Project Commands (Per Project)