fix(setup): create .ralphrc with consistent tool permissions (#137)
* fix(setup): create .ralphrc with consistent tool permissions (#136) - Update default ALLOWED_TOOLS in ralph_loop.sh to include Edit, Bash(npm *), and Bash(pytest) for test execution capability - Make setup.sh generate .ralphrc file using same permissions as ralph-enable, ensuring consistency between initialization paths - Add 8 new TDD tests for .ralphrc creation and ALLOWED_TOOLS defaults - Update documentation in README.md and CLAUDE.md This fixes the mismatch where PROMPT.md instructs the model to run tests, but the default permissions didn't allow it. Now both ralph-setup and ralph-enable create projects with identical tool permissions. Test count: 440 (up from 424) * fix: address PR review feedback - Update version badges from v0.10.1 to v0.11.2 (README.md) - Update test count badges from 310 to 440 (README.md, CLAUDE.md) - Fix .ralphrc generator label: use sed to replace "ralph enable" with "ralph-setup" when using generate_ralphrc() from library - Add v0.11.2 changelog entry to CLAUDE.md * docs(readme): comprehensive update for v0.11.2 - Reorganize Recent Improvements with v0.11.x versions prominent - Add ralph-enable wizard section with full documentation - Add .ralphrc configuration section with example - Update Quick Start to show ralph-enable as Option A (recommended) - Update test counts to 440 across 15 files - Collapse v0.9.x versions into expandable details section - Add new features to What's Working Now section - Link to issue #138 for automated badge updates - Update Command Reference with new commands --------- Co-authored-by: Test User <test@example.com>
This commit is contained in:
Frank Bria
GitHub
parent
33739e0fb2
commit
dbb27d89e9
7 changed files with 269 additions and 107 deletions
11
CLAUDE.md
11
CLAUDE.md
|
|
@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
|||
|
||||
This is the Ralph for Claude Code repository - an autonomous AI development loop system that enables continuous development cycles with intelligent exit detection and rate limiting.
|
||||
|
||||
**Version**: v0.11.1 | **Tests**: 424 passing (100% pass rate) | **CI/CD**: GitHub Actions
|
||||
**Version**: v0.11.2 | **Tests**: 440 passing (100% pass rate) | **CI/CD**: GitHub Actions
|
||||
|
||||
## Core Architecture
|
||||
|
||||
|
|
@ -205,7 +205,7 @@ 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_ALLOWED_TOOLS="Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)" # Allowed tool permissions
|
||||
CLAUDE_USE_CONTINUE=true # Enable session continuity
|
||||
CLAUDE_MIN_VERSION="2.0.76" # Minimum Claude CLI version
|
||||
```
|
||||
|
|
@ -436,6 +436,13 @@ bats tests/unit/test_cli_parsing.bats
|
|||
|
||||
## Recent Improvements
|
||||
|
||||
### Setup Permissions Fix (v0.11.2)
|
||||
- Fixed issue #136: `ralph-setup` now creates `.ralphrc` with consistent tool permissions
|
||||
- Updated default `ALLOWED_TOOLS` from `Write,Bash(git *),Read` to `Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)`
|
||||
- Both `ralph-setup` and `ralph-enable` now create identical `.ralphrc` configurations
|
||||
- Added 8 new TDD tests for `.ralphrc` creation and ALLOWED_TOOLS defaults
|
||||
- Test count: 440 (up from 424)
|
||||
|
||||
### Completion Indicators Fix (v0.11.1)
|
||||
- Fixed premature exit after exactly 5 loops in JSON output mode
|
||||
- Root cause: `update_exit_signals()` used confidence threshold (≥60) to populate `completion_indicators`
|
||||
|
|
|
|||
235
README.md
235
README.md
|
|
@ -2,8 +2,8 @@
|
|||
|
||||
[](https://github.com/frankbria/ralph-claude-code/actions/workflows/test.yml)
|
||||
[](LICENSE)
|
||||
|
||||
|
||||
|
||||
|
||||
[](https://github.com/frankbria/ralph-claude-code/issues)
|
||||
[](https://github.com/hesreallyhim/awesome-claude-code)
|
||||
[](https://x.com/FrankBria18044)
|
||||
|
|
@ -16,9 +16,9 @@ Ralph is an implementation of the Geoffrey Huntley's technique for Claude Code t
|
|||
|
||||
## Project Status
|
||||
|
||||
**Version**: v0.10.1 - Active Development
|
||||
**Version**: v0.11.2 - Active Development
|
||||
**Core Features**: Working and tested
|
||||
**Test Coverage**: 310 tests, 100% pass rate
|
||||
**Test Coverage**: 440 tests, 100% pass rate
|
||||
|
||||
### What's Working Now
|
||||
- Autonomous development loops with intelligent exit detection
|
||||
|
|
@ -30,107 +30,79 @@ Ralph is an implementation of the Geoffrey Huntley's technique for Claude Code t
|
|||
- **Session continuity with `--continue` flag for context preservation**
|
||||
- **Session expiration with configurable timeout (default: 24 hours)**
|
||||
- **Modern CLI flags: `--output-format`, `--allowed-tools`, `--no-continue`**
|
||||
- **Interactive project enablement with `ralph-enable` wizard**
|
||||
- **`.ralphrc` configuration file for project settings**
|
||||
- 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
|
||||
- **CI/CD pipeline with GitHub Actions**
|
||||
- **Dedicated uninstall script for clean removal**
|
||||
- 310 passing tests across 11 test files
|
||||
|
||||
### Recent Improvements
|
||||
|
||||
**v0.11.2 - Setup Permissions Fix** (latest)
|
||||
- Fixed issue #136: `ralph-setup` now creates `.ralphrc` with consistent tool permissions
|
||||
- Updated default `ALLOWED_TOOLS` to include `Edit`, `Bash(npm *)`, and `Bash(pytest)`
|
||||
- Both `ralph-setup` and `ralph-enable` now create identical `.ralphrc` configurations
|
||||
- Monitor now forwards all CLI parameters to inner ralph loop (#126)
|
||||
- Added 16 new tests for permissions and parameter forwarding
|
||||
|
||||
**v0.11.1 - Completion Indicators Fix**
|
||||
- Fixed premature exit after exactly 5 loops in JSON output mode
|
||||
- `completion_indicators` now only accumulates when `EXIT_SIGNAL: true`
|
||||
- Aligns with documented dual-condition exit gate behavior
|
||||
|
||||
**v0.11.0 - Ralph Enable Wizard**
|
||||
- Added `ralph-enable` interactive wizard for enabling Ralph in existing projects
|
||||
- 5-phase wizard: Environment Detection → Task Source Selection → Configuration → File Generation → Verification
|
||||
- Auto-detects project type (TypeScript, Python, Rust, Go) and framework (Next.js, FastAPI, Django)
|
||||
- Imports tasks from beads, GitHub Issues, or PRD documents
|
||||
- Added `ralph-enable-ci` non-interactive version for CI/automation
|
||||
- New library components: `enable_core.sh`, `wizard_utils.sh`, `task_sources.sh`
|
||||
|
||||
**v0.10.1 - Bug Fixes & Monitor Path Corrections**
|
||||
- Fixed `ralph_monitor.sh` hardcoded paths for v0.10.0 compatibility:
|
||||
- `STATUS_FILE`: `status.json` → `.ralph/status.json`
|
||||
- `LOG_FILE`: `logs/ralph.log` → `.ralph/logs/ralph.log`
|
||||
- `progress.json` → `.ralph/progress.json`
|
||||
- Fixed EXIT_SIGNAL parsing in JSON format (Bug #1):
|
||||
- Now extracts `EXIT_SIGNAL` from `.result` field when Claude CLI returns JSON
|
||||
- Properly detects RALPH_STATUS blocks embedded in JSON response text
|
||||
- Added safety circuit breaker (Bug #2):
|
||||
- Force exit after 5 consecutive completion indicators (prevents infinite loops)
|
||||
- Higher threshold than normal (2) to avoid false positives while preventing API waste
|
||||
- Fixed checkbox parsing for indented markdown (Bug #3):
|
||||
- Changed patterns from `^- \[` to `^[[:space:]]*- \[` (POSIX-compliant)
|
||||
- Supports indented checkboxes in `fix_plan.md`
|
||||
- Updated README.md documentation example for new log path
|
||||
- Fixed `ralph_monitor.sh` hardcoded paths for v0.10.0 compatibility
|
||||
- Fixed EXIT_SIGNAL parsing in JSON format
|
||||
- Added safety circuit breaker (force exit after 5 consecutive completion indicators)
|
||||
- Fixed checkbox parsing for indented markdown
|
||||
|
||||
**v0.10.0 - .ralph/ Subfolder Structure (BREAKING CHANGE)**
|
||||
- **Breaking**: Moved all Ralph-specific files to `.ralph/` subfolder
|
||||
- Project root stays clean: only `src/`, `README.md`, and user files remain
|
||||
- Added `ralph-migrate` command for upgrading existing projects
|
||||
- Migration script creates backup before moving files
|
||||
- Fail-safe migration: preserves dotfiles with `cp -a source/. dest/` pattern
|
||||
- Auto-detection of old structure with helpful upgrade guidance
|
||||
- Updated all tests for new structure (310 tests)
|
||||
|
||||
<details>
|
||||
<summary>Earlier versions (v0.9.x)</summary>
|
||||
|
||||
**v0.9.9 - EXIT_SIGNAL Gate & Uninstall Script**
|
||||
- Fixed premature exit bug: completion indicators now require Claude's explicit `EXIT_SIGNAL: true`
|
||||
- Added dual-condition check preventing exits when Claude reports work in progress
|
||||
- Added `response_analyzer.sh` fix to respect explicit EXIT_SIGNAL over heuristics
|
||||
- Added dedicated `uninstall.sh` script for clean Ralph removal
|
||||
- Session expiration with configurable timeout (default: 24 hours)
|
||||
- Added 32 new tests for EXIT_SIGNAL behavior and session expiration
|
||||
- Test count: 308 (up from 276)
|
||||
|
||||
**v0.9.8 - Modern CLI for PRD Import**
|
||||
- Modernized `ralph_import.sh` to use Claude Code CLI JSON output format
|
||||
- JSON output format support with `--output-format json` for structured responses
|
||||
- Enhanced error handling with structured JSON error messages
|
||||
- Improved file verification with JSON-derived status information
|
||||
- Backward compatibility with older CLI versions (automatic text fallback)
|
||||
- Added 11 new tests for modern CLI features
|
||||
|
||||
**v0.9.7 - Session Lifecycle Management**
|
||||
- Complete session lifecycle management with automatic reset triggers
|
||||
- Session auto-reset on: circuit breaker open, manual interrupt, project completion
|
||||
- Added `--reset-session` CLI flag for manual session reset
|
||||
- Session history tracking (last 50 transitions) for debugging
|
||||
- Added 26 new tests for session continuity features
|
||||
|
||||
**v0.9.6 - JSON Output & Session Management**
|
||||
- Extended `parse_json_response()` to support Claude Code CLI JSON format
|
||||
- Added session management functions: `store_session_id()`, `get_last_session_id()`, `should_resume_session()`
|
||||
- Cross-platform epoch time utilities in date_utils.sh
|
||||
- Added 16 new tests covering Claude CLI format and session management
|
||||
- Added session management functions
|
||||
|
||||
**v0.9.5 - PRD Import Tests**
|
||||
- Added 22 comprehensive tests for `ralph_import.sh` PRD conversion script
|
||||
- Tests cover: file format support, output file creation, project naming, error handling
|
||||
**v0.9.5 - v0.9.0** - PRD import tests, project setup tests, installation tests, prompt file fix, modern CLI commands, circuit breaker enhancements
|
||||
|
||||
**v0.9.4 - Project Setup Tests**
|
||||
- Added 36 comprehensive tests for `setup.sh` project initialization script
|
||||
- Tests cover: directory creation, template copying, git initialization
|
||||
|
||||
**v0.9.3 - Installation Tests**
|
||||
- Added 14 comprehensive tests for `install.sh` global installation script
|
||||
- Tests cover: directory creation, command installation, dependency detection
|
||||
|
||||
**v0.9.2 - Prompt File Fix**
|
||||
- Fixed critical bug: replaced non-existent `--prompt-file` CLI flag with `-p` flag
|
||||
- Modern CLI mode now correctly passes prompt content via `-p "$(cat file)"`
|
||||
- Added error handling for missing prompt files in `build_claude_command()`
|
||||
|
||||
**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
|
||||
- CI/CD pipeline with kcov coverage reporting
|
||||
|
||||
**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`)
|
||||
- Added two-stage error filtering for accurate detection
|
||||
</details>
|
||||
|
||||
### In Progress
|
||||
- Expanding test coverage
|
||||
- Log rotation functionality
|
||||
- Dry-run mode
|
||||
- Configuration file support (.ralphrc)
|
||||
- Metrics and analytics tracking
|
||||
- Desktop notifications
|
||||
- Git backup and rollback system
|
||||
- [Automated badge updates](#138)
|
||||
|
||||
**Timeline to v1.0**: ~4 weeks | [Full roadmap](IMPLEMENTATION_PLAN.md) | **Contributions welcome!**
|
||||
|
||||
|
|
@ -145,6 +117,8 @@ Ralph is an implementation of the Geoffrey Huntley's technique for Claude Code t
|
|||
- **Live Monitoring** - Real-time dashboard showing loop status, progress, and logs
|
||||
- **Task Management** - Structured approach with prioritized task lists and progress tracking
|
||||
- **Project Templates** - Quick setup for new projects with best-practice structure
|
||||
- **Interactive Project Setup** - `ralph-enable` wizard for existing projects with task import
|
||||
- **Configuration Files** - `.ralphrc` for project-specific settings and tool permissions
|
||||
- **Comprehensive Logging** - Detailed execution logs with timestamps and status tracking
|
||||
- **Configurable Timeouts** - Set execution timeout for Claude Code operations (1-120 minutes)
|
||||
- **Verbose Progress Mode** - Optional detailed progress updates during execution
|
||||
|
|
@ -161,8 +135,8 @@ Ralph has two phases: **one-time installation** and **per-project setup**.
|
|||
INSTALL ONCE USE MANY TIMES
|
||||
+-----------------+ +----------------------+
|
||||
| ./install.sh | -> | ralph-setup project1 |
|
||||
| | | ralph-setup project2 |
|
||||
| Adds global | | ralph-setup project3 |
|
||||
| | | ralph-enable |
|
||||
| Adds global | | ralph-import prd.md |
|
||||
| commands | | ... |
|
||||
+-----------------+ +----------------------+
|
||||
```
|
||||
|
|
@ -177,17 +151,31 @@ cd ralph-claude-code
|
|||
./install.sh
|
||||
```
|
||||
|
||||
This adds `ralph`, `ralph-monitor`, `ralph-setup`, `ralph-import`, and `ralph-migrate` commands to your PATH.
|
||||
This adds `ralph`, `ralph-monitor`, `ralph-setup`, `ralph-import`, `ralph-migrate`, `ralph-enable`, and `ralph-enable-ci` commands to your PATH.
|
||||
|
||||
> **Note**: You only need to do this once per system. After installation, you can delete the cloned repository if desired.
|
||||
|
||||
### Phase 2: Initialize New Projects (Per Project)
|
||||
### Phase 2: Initialize Projects (Per Project)
|
||||
|
||||
For each new project you want Ralph to work on:
|
||||
|
||||
#### Option A: Import Existing PRD/Specifications
|
||||
#### Option A: Enable Ralph in Existing Project (Recommended)
|
||||
```bash
|
||||
# Convert existing PRD/specs to Ralph format (recommended)
|
||||
cd my-existing-project
|
||||
|
||||
# Interactive wizard - auto-detects project type and imports tasks
|
||||
ralph-enable
|
||||
|
||||
# Or with specific task source
|
||||
ralph-enable --from beads
|
||||
ralph-enable --from github --label "sprint-1"
|
||||
ralph-enable --from prd ./docs/requirements.md
|
||||
|
||||
# Start autonomous development
|
||||
ralph --monitor
|
||||
```
|
||||
|
||||
#### Option B: Import Existing PRD/Specifications
|
||||
```bash
|
||||
# Convert existing PRD/specs to Ralph format
|
||||
ralph-import my-requirements.md my-project
|
||||
cd my-project
|
||||
|
||||
|
|
@ -200,7 +188,7 @@ cd my-project
|
|||
ralph --monitor
|
||||
```
|
||||
|
||||
#### Option B: Manual Project Setup
|
||||
#### Option C: Create New Project from Scratch
|
||||
```bash
|
||||
# Create blank Ralph project
|
||||
ralph-setup my-awesome-project
|
||||
|
|
@ -277,6 +265,30 @@ Loop 8: Claude outputs "All tasks complete, project ready"
|
|||
- Too many test-focused loops (indicating feature completeness)
|
||||
- Claude API 5-hour usage limit reached (with user prompt to wait or exit)
|
||||
|
||||
## Enabling Ralph in Existing Projects
|
||||
|
||||
The `ralph-enable` command provides an interactive wizard for adding Ralph to existing projects:
|
||||
|
||||
```bash
|
||||
cd my-existing-project
|
||||
ralph-enable
|
||||
```
|
||||
|
||||
**The wizard:**
|
||||
1. **Detects Environment** - Identifies project type (TypeScript, Python, etc.) and framework
|
||||
2. **Selects Task Sources** - Choose from beads, GitHub Issues, or PRD documents
|
||||
3. **Configures Settings** - Set tool permissions and loop parameters
|
||||
4. **Generates Files** - Creates `.ralph/` directory and `.ralphrc` configuration
|
||||
5. **Verifies Setup** - Confirms all files are created correctly
|
||||
|
||||
**Non-interactive mode for CI/automation:**
|
||||
```bash
|
||||
ralph-enable-ci # Sensible defaults
|
||||
ralph-enable-ci --from github # Import from GitHub Issues
|
||||
ralph-enable-ci --project-type typescript # Override detection
|
||||
ralph-enable-ci --json # Machine-readable output
|
||||
```
|
||||
|
||||
## Importing Existing Requirements
|
||||
|
||||
Ralph can convert existing PRDs, specifications, or requirement documents into the proper Ralph format using Claude Code.
|
||||
|
|
@ -312,23 +324,39 @@ Ralph-import creates a complete project with:
|
|||
- **.ralph/PROMPT.md** - Converted into Ralph development instructions
|
||||
- **.ralph/fix_plan.md** - Requirements broken down into prioritized tasks
|
||||
- **.ralph/specs/requirements.md** - Technical specifications extracted from your document
|
||||
- **.ralphrc** - Project configuration file with tool permissions
|
||||
- **Standard Ralph structure** - All necessary directories and template files in `.ralph/`
|
||||
|
||||
The conversion is intelligent and preserves your original requirements while making them actionable for autonomous development.
|
||||
|
||||
### Modern CLI Features (v0.9.8)
|
||||
|
||||
Ralph-import uses modern Claude Code CLI features for improved reliability:
|
||||
|
||||
- **JSON Output Format**: Structured responses enable precise parsing of conversion results
|
||||
- **Automatic Fallback**: Gracefully handles older CLI versions with text-based parsing
|
||||
- **Enhanced Error Reporting**: Extracts specific error messages and codes from JSON responses
|
||||
- **Session Tracking**: Captures session IDs for potential continuation of interrupted conversions
|
||||
|
||||
> **Note**: These features require Claude Code CLI version 2.0.76 or later. Older versions will work with standard text output.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Project Configuration (.ralphrc)
|
||||
|
||||
Each Ralph project can have a `.ralphrc` configuration file:
|
||||
|
||||
```bash
|
||||
# .ralphrc - Ralph project configuration
|
||||
PROJECT_NAME="my-project"
|
||||
PROJECT_TYPE="typescript"
|
||||
|
||||
# Loop settings
|
||||
MAX_CALLS_PER_HOUR=100
|
||||
CLAUDE_TIMEOUT_MINUTES=15
|
||||
CLAUDE_OUTPUT_FORMAT="json"
|
||||
|
||||
# Tool permissions
|
||||
ALLOWED_TOOLS="Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)"
|
||||
|
||||
# Session management
|
||||
SESSION_CONTINUITY=true
|
||||
SESSION_EXPIRY_HOURS=24
|
||||
|
||||
# Circuit breaker thresholds
|
||||
CB_NO_PROGRESS_THRESHOLD=3
|
||||
CB_SAME_ERROR_THRESHOLD=5
|
||||
```
|
||||
|
||||
### Rate Limiting & Circuit Breaker
|
||||
|
||||
Ralph includes intelligent rate limiting and circuit breaker functionality:
|
||||
|
|
@ -457,13 +485,14 @@ Ralph creates a standardized structure for each project with a `.ralph/` subfold
|
|||
my-project/
|
||||
├── .ralph/ # Ralph configuration and state (hidden folder)
|
||||
│ ├── PROMPT.md # Main development instructions for Ralph
|
||||
│ ├── fix_plan.md # Prioritized task list (@ prefix = Ralph control file)
|
||||
│ ├── fix_plan.md # Prioritized task list
|
||||
│ ├── AGENT.md # Build and run instructions
|
||||
│ ├── specs/ # Project specifications and requirements
|
||||
│ │ └── stdlib/ # Standard library specifications
|
||||
│ ├── examples/ # Usage examples and test cases
|
||||
│ ├── logs/ # Ralph execution logs
|
||||
│ └── docs/generated/ # Auto-generated documentation
|
||||
├── .ralphrc # Ralph configuration file (tool permissions, settings)
|
||||
└── src/ # Source code implementation (at project root)
|
||||
```
|
||||
|
||||
|
|
@ -514,7 +543,7 @@ If you want to run the test suite:
|
|||
# Install BATS testing framework
|
||||
npm install -g bats bats-support bats-assert
|
||||
|
||||
# Run all tests (308 tests)
|
||||
# Run all tests (440 tests)
|
||||
npm test
|
||||
|
||||
# Run specific test suites
|
||||
|
|
@ -524,6 +553,10 @@ bats tests/unit/test_json_parsing.bats
|
|||
bats tests/unit/test_cli_modern.bats
|
||||
bats tests/unit/test_cli_parsing.bats
|
||||
bats tests/unit/test_session_continuity.bats
|
||||
bats tests/unit/test_enable_core.bats
|
||||
bats tests/unit/test_task_sources.bats
|
||||
bats tests/unit/test_ralph_enable.bats
|
||||
bats tests/unit/test_wizard_utils.bats
|
||||
bats tests/integration/test_loop_execution.bats
|
||||
bats tests/integration/test_prd_import.bats
|
||||
bats tests/integration/test_project_setup.bats
|
||||
|
|
@ -535,10 +568,10 @@ bats tests/integration/test_installation.bats
|
|||
```
|
||||
|
||||
Current test status:
|
||||
- **308 tests** across 11 test files
|
||||
- **100% pass rate** (308/308 passing)
|
||||
- **440 tests** across 15 test files
|
||||
- **100% pass rate** (440/440 passing)
|
||||
- Comprehensive unit and integration tests
|
||||
- Specialized tests for JSON parsing, CLI flags, circuit breaker, EXIT_SIGNAL behavior, and installation workflows
|
||||
- Specialized tests for JSON parsing, CLI flags, circuit breaker, EXIT_SIGNAL behavior, enable wizard, and installation workflows
|
||||
|
||||
> **Note on Coverage**: Bash code coverage measurement with kcov has fundamental limitations when tracing subprocess executions. Test pass rate (100%) is the quality gate. See [bats-core#15](https://github.com/bats-core/bats-core/issues/15) for details.
|
||||
|
||||
|
|
@ -637,13 +670,13 @@ cd ralph-claude-code
|
|||
|
||||
# Install dependencies and run tests
|
||||
npm install
|
||||
npm test # All 308 tests must pass
|
||||
npm test # All 440 tests must pass
|
||||
```
|
||||
|
||||
### Priority Contribution Areas
|
||||
|
||||
1. **Test Implementation** - Help expand test coverage
|
||||
2. **Feature Development** - Log rotation, dry-run mode, config files, metrics
|
||||
2. **Feature Development** - Log rotation, dry-run mode, metrics
|
||||
3. **Documentation** - Tutorials, troubleshooting guides, examples
|
||||
4. **Real-World Testing** - Use Ralph, report bugs, share feedback
|
||||
|
||||
|
|
@ -688,7 +721,7 @@ ralph [OPTIONS]
|
|||
-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)
|
||||
--allowed-tools TOOLS Set allowed Claude tools (default: Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest))
|
||||
--no-continue Disable session continuity (start fresh each loop)
|
||||
--reset-circuit Reset the circuit breaker
|
||||
--circuit-status Show circuit breaker status
|
||||
|
|
@ -698,6 +731,8 @@ ralph [OPTIONS]
|
|||
### Project Commands (Per Project)
|
||||
```bash
|
||||
ralph-setup project-name # Create new Ralph project
|
||||
ralph-enable # Enable Ralph in existing project (interactive)
|
||||
ralph-enable-ci # Enable Ralph in existing project (non-interactive)
|
||||
ralph-import prd.md project # Convert PRD/specs to Ralph project
|
||||
ralph --monitor # Start with integrated monitoring
|
||||
ralph --status # Check current loop status
|
||||
|
|
@ -721,28 +756,29 @@ tmux attach -t <name> # Reattach to detached session
|
|||
|
||||
Ralph is under active development with a clear path to v1.0.0. See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) for the complete roadmap.
|
||||
|
||||
### Current Status: v0.9.9
|
||||
### Current Status: v0.11.2
|
||||
|
||||
**What's Delivered:**
|
||||
- Core loop functionality with intelligent exit detection
|
||||
- **Dual-condition exit gate** (completion indicators + EXIT_SIGNAL)
|
||||
- Rate limiting (100 calls/hour) and circuit breaker pattern
|
||||
- Response analyzer with semantic understanding
|
||||
- 308 comprehensive tests (100% pass rate)
|
||||
- **440 comprehensive tests** (100% pass rate)
|
||||
- tmux integration and live monitoring
|
||||
- PRD import functionality with modern CLI JSON parsing
|
||||
- Installation system and project templates
|
||||
- Modern CLI commands with JSON output support
|
||||
- CI/CD pipeline with GitHub Actions
|
||||
- Comprehensive installation test suite
|
||||
- **Interactive `ralph-enable` wizard for existing projects**
|
||||
- **`.ralphrc` configuration file support**
|
||||
- Session lifecycle management with auto-reset triggers
|
||||
- Session expiration with configurable timeout
|
||||
- Dedicated uninstall script
|
||||
|
||||
**Test Coverage Breakdown:**
|
||||
- Unit Tests: 164 (CLI parsing, JSON, exit detection, rate limiting, session continuity)
|
||||
- Unit Tests: 296 (CLI parsing, JSON, exit detection, rate limiting, session continuity, enable wizard)
|
||||
- Integration Tests: 144 (loop execution, edge cases, installation, project setup, PRD import)
|
||||
- Test Files: 11
|
||||
- Test Files: 15
|
||||
|
||||
### Path to v1.0.0 (~4 weeks)
|
||||
|
||||
|
|
@ -754,7 +790,6 @@ Ralph is under active development with a clear path to v1.0.0. See [IMPLEMENTATI
|
|||
**Core Features**
|
||||
- Log rotation functionality
|
||||
- Dry-run mode
|
||||
- Configuration file support - .ralphrc
|
||||
|
||||
**Advanced Features & Polish**
|
||||
- Metrics and analytics tracking
|
||||
|
|
@ -768,7 +803,7 @@ See [IMPLEMENTATION_STATUS.md](IMPLEMENTATION_STATUS.md) for detailed progress t
|
|||
### How to Contribute
|
||||
Ralph is seeking contributors! See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete guide. Priority areas:
|
||||
1. **Test Implementation** - Help expand test coverage ([see plan](IMPLEMENTATION_PLAN.md))
|
||||
2. **Feature Development** - Log rotation, dry-run mode, config files
|
||||
2. **Feature Development** - Log rotation, dry-run mode, metrics
|
||||
3. **Documentation** - Usage examples, tutorials, troubleshooting guides
|
||||
4. **Bug Reports** - Real-world usage feedback and edge cases
|
||||
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ CLAUDE_TIMEOUT_MINUTES="${CLAUDE_TIMEOUT_MINUTES:-15}"
|
|||
|
||||
# Modern Claude CLI configuration (Phase 1.1)
|
||||
CLAUDE_OUTPUT_FORMAT="${CLAUDE_OUTPUT_FORMAT:-json}"
|
||||
CLAUDE_ALLOWED_TOOLS="${CLAUDE_ALLOWED_TOOLS:-Write,Bash(git *),Read}"
|
||||
CLAUDE_ALLOWED_TOOLS="${CLAUDE_ALLOWED_TOOLS:-Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)}"
|
||||
CLAUDE_USE_CONTINUE="${CLAUDE_USE_CONTINUE:-true}"
|
||||
CLAUDE_SESSION_FILE="$RALPH_DIR/.claude_session_id" # Session ID persistence file
|
||||
CLAUDE_MIN_VERSION="2.0.76" # Minimum required Claude CLI version
|
||||
|
|
@ -217,7 +217,7 @@ setup_tmux_session() {
|
|||
ralph_cmd="$ralph_cmd --timeout $CLAUDE_TIMEOUT_MINUTES"
|
||||
fi
|
||||
# Forward --allowed-tools if non-default
|
||||
if [[ "$CLAUDE_ALLOWED_TOOLS" != "Write,Bash(git *),Read" ]]; then
|
||||
if [[ "$CLAUDE_ALLOWED_TOOLS" != "Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)" ]]; then
|
||||
ralph_cmd="$ralph_cmd --allowed-tools '$CLAUDE_ALLOWED_TOOLS'"
|
||||
fi
|
||||
# Forward --no-continue if session continuity disabled
|
||||
|
|
|
|||
48
setup.sh
48
setup.sh
|
|
@ -15,10 +15,13 @@ cd "$PROJECT_NAME"
|
|||
# Determine templates directory location (checked AFTER cd into project)
|
||||
# Check local ../templates first, then global ~/.ralph/templates
|
||||
TEMPLATES_DIR=""
|
||||
LIB_DIR=""
|
||||
if [[ -d "../templates" ]]; then
|
||||
TEMPLATES_DIR="../templates"
|
||||
LIB_DIR="../lib"
|
||||
elif [[ -d "$HOME/.ralph/templates" ]]; then
|
||||
TEMPLATES_DIR="$HOME/.ralph/templates"
|
||||
LIB_DIR="$HOME/.ralph/lib"
|
||||
else
|
||||
echo "❌ Error: Templates directory not found."
|
||||
echo " Expected at: ../templates or ~/.ralph/templates"
|
||||
|
|
@ -44,6 +47,51 @@ cp "$TEMPLATES_DIR/fix_plan.md" .ralph/fix_plan.md
|
|||
cp "$TEMPLATES_DIR/AGENT.md" .ralph/AGENT.md
|
||||
cp -r "$TEMPLATES_DIR/specs"/* .ralph/specs/ 2>/dev/null || true
|
||||
|
||||
# Generate .ralphrc configuration file
|
||||
# Source enable_core.sh if available for generate_ralphrc(), otherwise create inline
|
||||
if [[ -f "$LIB_DIR/enable_core.sh" ]]; then
|
||||
# Temporarily disable colors for cleaner output
|
||||
export ENABLE_USE_COLORS=false
|
||||
source "$LIB_DIR/enable_core.sh"
|
||||
# Generate .ralphrc and fix the generator label (library says "ralph enable")
|
||||
generate_ralphrc "$PROJECT_NAME" "generic" "local" | sed 's/Generated by: ralph enable/Generated by: ralph-setup/' > .ralphrc
|
||||
else
|
||||
# Fallback: create minimal .ralphrc inline (same content as generate_ralphrc)
|
||||
cat > .ralphrc << RALPHRCEOF
|
||||
# .ralphrc - Ralph project configuration
|
||||
# Generated by: ralph-setup
|
||||
# Documentation: https://github.com/frankbria/ralph-claude-code
|
||||
|
||||
# Project identification
|
||||
PROJECT_NAME="${PROJECT_NAME}"
|
||||
PROJECT_TYPE="generic"
|
||||
|
||||
# Loop settings
|
||||
MAX_CALLS_PER_HOUR=100
|
||||
CLAUDE_TIMEOUT_MINUTES=15
|
||||
CLAUDE_OUTPUT_FORMAT="json"
|
||||
|
||||
# Tool permissions
|
||||
# Comma-separated list of allowed tools
|
||||
ALLOWED_TOOLS="Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)"
|
||||
|
||||
# Session management
|
||||
SESSION_CONTINUITY=true
|
||||
SESSION_EXPIRY_HOURS=24
|
||||
|
||||
# Task sources (for ralph enable --sync)
|
||||
# Options: local, beads, github (comma-separated for multiple)
|
||||
TASK_SOURCES="local"
|
||||
GITHUB_TASK_LABEL="ralph-task"
|
||||
BEADS_FILTER="status:open"
|
||||
|
||||
# Circuit breaker thresholds
|
||||
CB_NO_PROGRESS_THRESHOLD=3
|
||||
CB_SAME_ERROR_THRESHOLD=5
|
||||
CB_OUTPUT_DECLINE_THRESHOLD=70
|
||||
RALPHRCEOF
|
||||
fi
|
||||
|
||||
# Initialize git
|
||||
git init
|
||||
echo "# $PROJECT_NAME" > README.md
|
||||
|
|
|
|||
|
|
@ -489,3 +489,57 @@ teardown() {
|
|||
# The script properly quotes variables, so spaces should be handled correctly
|
||||
[[ $status -eq 0 ]]
|
||||
}
|
||||
|
||||
# =============================================================================
|
||||
# Test: .ralphrc Generation (Issue #136)
|
||||
# =============================================================================
|
||||
|
||||
@test "setup.sh creates .ralphrc file" {
|
||||
run bash "$SETUP_SCRIPT" test-project
|
||||
|
||||
assert_success
|
||||
assert_file_exists "test-project/.ralphrc"
|
||||
}
|
||||
|
||||
@test "setup.sh .ralphrc contains ALLOWED_TOOLS with Edit" {
|
||||
bash "$SETUP_SCRIPT" test-project
|
||||
|
||||
# .ralphrc should include Edit tool
|
||||
grep -q "Edit" test-project/.ralphrc
|
||||
}
|
||||
|
||||
@test "setup.sh .ralphrc contains ALLOWED_TOOLS with test execution capabilities" {
|
||||
bash "$SETUP_SCRIPT" test-project
|
||||
|
||||
# .ralphrc should include Bash(npm *) or Bash(pytest) for test execution
|
||||
grep -qE 'Bash\(npm \*\)|Bash\(pytest\)' test-project/.ralphrc
|
||||
}
|
||||
|
||||
@test "setup.sh .ralphrc ALLOWED_TOOLS matches ralph-enable defaults" {
|
||||
bash "$SETUP_SCRIPT" test-project
|
||||
|
||||
# The expected ALLOWED_TOOLS value that ralph-enable uses
|
||||
local expected_tools='ALLOWED_TOOLS="Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)"'
|
||||
|
||||
# Check that .ralphrc contains the expected ALLOWED_TOOLS line
|
||||
# Use grep -F for literal string matching (avoids regex interpretation of *)
|
||||
grep -qF "$expected_tools" test-project/.ralphrc
|
||||
}
|
||||
|
||||
@test "setup.sh .ralphrc is committed in initial git commit" {
|
||||
bash "$SETUP_SCRIPT" test-project
|
||||
|
||||
cd test-project
|
||||
# Verify .ralphrc is tracked by git (not in untracked files)
|
||||
run command git ls-files .ralphrc
|
||||
|
||||
assert_success
|
||||
assert_equal "$output" ".ralphrc"
|
||||
}
|
||||
|
||||
@test "setup.sh .ralphrc contains project name" {
|
||||
bash "$SETUP_SCRIPT" my-custom-project
|
||||
|
||||
# .ralphrc should reference the project name
|
||||
grep -q "my-custom-project" my-custom-project/.ralphrc
|
||||
}
|
||||
|
|
|
|||
|
|
@ -171,6 +171,24 @@ teardown() {
|
|||
[[ "$output" == *"Read"* ]]
|
||||
}
|
||||
|
||||
@test "CLAUDE_ALLOWED_TOOLS default includes Edit tool (issue #136)" {
|
||||
# Verify the default includes Edit for file editing
|
||||
run grep 'CLAUDE_ALLOWED_TOOLS=.*:-' "${BATS_TEST_DIRNAME}/../../ralph_loop.sh"
|
||||
|
||||
# The default should include Edit
|
||||
[[ "$output" == *"Edit"* ]]
|
||||
}
|
||||
|
||||
@test "CLAUDE_ALLOWED_TOOLS default includes test execution tools (issue #136)" {
|
||||
# Verify the default includes test execution capabilities
|
||||
run grep 'CLAUDE_ALLOWED_TOOLS=.*:-' "${BATS_TEST_DIRNAME}/../../ralph_loop.sh"
|
||||
|
||||
# Should include Bash(npm *) for npm test
|
||||
[[ "$output" == *'Bash(npm *)'* ]]
|
||||
# Should include Bash(pytest) for Python tests
|
||||
[[ "$output" == *'Bash(pytest)'* ]]
|
||||
}
|
||||
|
||||
@test "CLAUDE_USE_CONTINUE defaults to true" {
|
||||
# Verify by checking the default in ralph_loop.sh via grep
|
||||
run grep 'CLAUDE_USE_CONTINUE=' "${BATS_TEST_DIRNAME}/../../ralph_loop.sh"
|
||||
|
|
|
|||
|
|
@ -377,7 +377,7 @@ build_ralph_cmd_for_test() {
|
|||
local CLAUDE_OUTPUT_FORMAT="${3:-json}"
|
||||
local VERBOSE_PROGRESS="${4:-false}"
|
||||
local CLAUDE_TIMEOUT_MINUTES="${5:-15}"
|
||||
local CLAUDE_ALLOWED_TOOLS="${6:-Write,Bash(git *),Read}"
|
||||
local CLAUDE_ALLOWED_TOOLS="${6:-Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)}"
|
||||
local CLAUDE_USE_CONTINUE="${7:-true}"
|
||||
local CLAUDE_SESSION_EXPIRY_HOURS="${8:-24}"
|
||||
local RALPH_DIR=".ralph"
|
||||
|
|
@ -403,7 +403,7 @@ build_ralph_cmd_for_test() {
|
|||
ralph_cmd="$ralph_cmd --timeout $CLAUDE_TIMEOUT_MINUTES"
|
||||
fi
|
||||
# Forward --allowed-tools if non-default
|
||||
if [[ "$CLAUDE_ALLOWED_TOOLS" != "Write,Bash(git *),Read" ]]; then
|
||||
if [[ "$CLAUDE_ALLOWED_TOOLS" != "Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)" ]]; then
|
||||
ralph_cmd="$ralph_cmd --allowed-tools '$CLAUDE_ALLOWED_TOOLS'"
|
||||
fi
|
||||
# Forward --no-continue if session continuity disabled
|
||||
|
|
@ -460,7 +460,7 @@ build_ralph_cmd_for_test() {
|
|||
}
|
||||
|
||||
@test "monitor does not forward default parameters" {
|
||||
local result=$(build_ralph_cmd_for_test 100 ".ralph/PROMPT.md" "json" "false" "15" "Write,Bash(git *),Read" "true" "24")
|
||||
local result=$(build_ralph_cmd_for_test 100 ".ralph/PROMPT.md" "json" "false" "15" "Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)" "true" "24")
|
||||
# Should only be "ralph" with no extra flags
|
||||
[[ "$result" == "ralph" ]]
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue