4b1ca9bcc7
- Add --output-format json flag for structured Claude CLI responses - Implement detect_response_format() for JSON vs text detection - Implement parse_conversion_response() for extracting JSON fields - Add check_claude_version() for modern CLI feature detection - Enhance error handling with structured JSON error messages - Improve file verification with JSON-derived status information - Maintain backward compatibility with automatic text fallback - Add 11 new TDD tests for modern CLI features (tests 23-33) - Update README.md with Modern CLI Features section - Update CLAUDE.md with v0.9.8 release notes Test count: 276 (up from 265)
484 lines
No EOL
14 KiB
Bash
Executable file
484 lines
No EOL
14 KiB
Bash
Executable file
#!/bin/bash
|
|
|
|
# Ralph Import - Convert PRDs to Ralph format using Claude Code
|
|
# Version: 0.9.8 - Modern CLI support with JSON output parsing
|
|
set -e
|
|
|
|
# Configuration
|
|
CLAUDE_CODE_CMD="claude"
|
|
|
|
# Modern CLI Configuration (Phase 1.1)
|
|
# These flags enable structured JSON output and controlled file operations
|
|
CLAUDE_OUTPUT_FORMAT="json"
|
|
CLAUDE_ALLOWED_TOOLS='"Read" "Write" "Bash(mkdir:*)" "Bash(cp:*)"'
|
|
CLAUDE_MIN_VERSION="2.0.76" # Minimum version for modern CLI features
|
|
|
|
# Temporary file names
|
|
CONVERSION_OUTPUT_FILE=".ralph_conversion_output.json"
|
|
CONVERSION_PROMPT_FILE=".ralph_conversion_prompt.md"
|
|
|
|
# Colors
|
|
RED='\033[0;31m'
|
|
GREEN='\033[0;32m'
|
|
YELLOW='\033[1;33m'
|
|
BLUE='\033[0;34m'
|
|
NC='\033[0m'
|
|
|
|
log() {
|
|
local level=$1
|
|
local message=$2
|
|
local color=""
|
|
|
|
case $level in
|
|
"INFO") color=$BLUE ;;
|
|
"WARN") color=$YELLOW ;;
|
|
"ERROR") color=$RED ;;
|
|
"SUCCESS") color=$GREEN ;;
|
|
esac
|
|
|
|
echo -e "${color}[$(date '+%H:%M:%S')] [$level] $message${NC}"
|
|
}
|
|
|
|
# =============================================================================
|
|
# JSON OUTPUT FORMAT DETECTION AND PARSING
|
|
# =============================================================================
|
|
|
|
# Detect output format (json or text)
|
|
# Returns: "json" if valid JSON, "text" otherwise
|
|
detect_response_format() {
|
|
local output_file=$1
|
|
|
|
if [[ ! -f "$output_file" ]] || [[ ! -s "$output_file" ]]; then
|
|
echo "text"
|
|
return
|
|
fi
|
|
|
|
# Check if file starts with { or [ (JSON indicators)
|
|
local first_char=$(head -c 1 "$output_file" 2>/dev/null | tr -d '[:space:]')
|
|
|
|
if [[ "$first_char" != "{" && "$first_char" != "[" ]]; then
|
|
echo "text"
|
|
return
|
|
fi
|
|
|
|
# Validate as JSON using jq
|
|
if command -v jq &>/dev/null && jq empty "$output_file" 2>/dev/null; then
|
|
echo "json"
|
|
else
|
|
echo "text"
|
|
fi
|
|
}
|
|
|
|
# Parse JSON response and extract conversion status
|
|
# Returns: 0 on success, 1 on error
|
|
# Sets global variables for parsed values
|
|
parse_conversion_response() {
|
|
local output_file=$1
|
|
|
|
if [[ ! -f "$output_file" ]]; then
|
|
return 1
|
|
fi
|
|
|
|
# Check if jq is available
|
|
if ! command -v jq &>/dev/null; then
|
|
log "WARN" "jq not found, skipping JSON parsing"
|
|
return 1
|
|
fi
|
|
|
|
# Validate JSON first
|
|
if ! jq empty "$output_file" 2>/dev/null; then
|
|
log "WARN" "Invalid JSON in output, falling back to text parsing"
|
|
return 1
|
|
fi
|
|
|
|
# Extract fields from JSON response
|
|
# Supports both flat format and Claude CLI format with metadata
|
|
|
|
# Result/summary field
|
|
PARSED_RESULT=$(jq -r '.result // .summary // ""' "$output_file" 2>/dev/null)
|
|
|
|
# Session ID (for potential continuation)
|
|
PARSED_SESSION_ID=$(jq -r '.sessionId // .session_id // ""' "$output_file" 2>/dev/null)
|
|
|
|
# Files changed count
|
|
PARSED_FILES_CHANGED=$(jq -r '.metadata.files_changed // .files_changed // 0' "$output_file" 2>/dev/null)
|
|
|
|
# Has errors flag
|
|
PARSED_HAS_ERRORS=$(jq -r '.metadata.has_errors // .has_errors // false' "$output_file" 2>/dev/null)
|
|
|
|
# Completion status
|
|
PARSED_COMPLETION_STATUS=$(jq -r '.metadata.completion_status // .completion_status // "unknown"' "$output_file" 2>/dev/null)
|
|
|
|
# Error message (if any)
|
|
PARSED_ERROR_MESSAGE=$(jq -r '.metadata.error_message // .error_message // ""' "$output_file" 2>/dev/null)
|
|
|
|
# Error code (if any)
|
|
PARSED_ERROR_CODE=$(jq -r '.metadata.error_code // .error_code // ""' "$output_file" 2>/dev/null)
|
|
|
|
# Files created (as array)
|
|
PARSED_FILES_CREATED=$(jq -r '.metadata.files_created // [] | @json' "$output_file" 2>/dev/null)
|
|
|
|
# Missing files (as array)
|
|
PARSED_MISSING_FILES=$(jq -r '.metadata.missing_files // [] | @json' "$output_file" 2>/dev/null)
|
|
|
|
return 0
|
|
}
|
|
|
|
# Check Claude Code CLI version for modern features
|
|
check_claude_version() {
|
|
local version
|
|
version=$($CLAUDE_CODE_CMD --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
|
|
|
|
if [[ -z "$version" ]]; then
|
|
log "WARN" "Could not determine Claude Code CLI version"
|
|
return 1
|
|
fi
|
|
|
|
# Simple version comparison (assumes semantic versioning)
|
|
# For production use, consider a more robust version comparison
|
|
if [[ "$version" < "$CLAUDE_MIN_VERSION" ]]; then
|
|
log "WARN" "Claude Code CLI version $version is below recommended $CLAUDE_MIN_VERSION"
|
|
return 1
|
|
fi
|
|
|
|
return 0
|
|
}
|
|
|
|
show_help() {
|
|
cat << HELPEOF
|
|
Ralph Import - Convert PRDs to Ralph Format
|
|
|
|
Usage: $0 <source-file> [project-name]
|
|
|
|
Arguments:
|
|
source-file Path to your PRD/specification file (any format)
|
|
project-name Name for the new Ralph project (optional, defaults to filename)
|
|
|
|
Examples:
|
|
$0 my-app-prd.md
|
|
$0 requirements.txt my-awesome-app
|
|
$0 project-spec.json
|
|
$0 design-doc.docx webapp
|
|
|
|
Supported formats:
|
|
- Markdown (.md)
|
|
- Text files (.txt)
|
|
- JSON (.json)
|
|
- Word documents (.docx)
|
|
- PDFs (.pdf)
|
|
- Any text-based format
|
|
|
|
The command will:
|
|
1. Create a new Ralph project
|
|
2. Use Claude Code to intelligently convert your PRD into:
|
|
- PROMPT.md (Ralph instructions)
|
|
- @fix_plan.md (prioritized tasks)
|
|
- specs/ (technical specifications)
|
|
|
|
HELPEOF
|
|
}
|
|
|
|
# Check dependencies
|
|
check_dependencies() {
|
|
if ! command -v ralph-setup &> /dev/null; then
|
|
log "ERROR" "Ralph not installed. Run ./install.sh first"
|
|
exit 1
|
|
fi
|
|
|
|
if ! npx @anthropic/claude-code --version &> /dev/null 2>&1; then
|
|
log "WARN" "Claude Code CLI not found. It will be downloaded when first used."
|
|
fi
|
|
}
|
|
|
|
# Convert PRD using Claude Code
|
|
convert_prd() {
|
|
local source_file=$1
|
|
local project_name=$2
|
|
local use_modern_cli=true
|
|
local cli_exit_code=0
|
|
|
|
log "INFO" "Converting PRD to Ralph format using Claude Code..."
|
|
|
|
# Check for modern CLI support
|
|
if ! check_claude_version 2>/dev/null; then
|
|
log "INFO" "Using standard CLI mode (modern features may not be available)"
|
|
use_modern_cli=false
|
|
else
|
|
log "INFO" "Using modern CLI with JSON output format"
|
|
fi
|
|
|
|
# Create conversion prompt
|
|
cat > "$CONVERSION_PROMPT_FILE" << 'PROMPTEOF'
|
|
# PRD to Ralph Conversion Task
|
|
|
|
You are tasked with converting a Product Requirements Document (PRD) or specification into Ralph for Claude Code format.
|
|
|
|
## Input Analysis
|
|
Analyze the provided specification file and extract:
|
|
- Project goals and objectives
|
|
- Core features and requirements
|
|
- Technical constraints and preferences
|
|
- Priority levels and phases
|
|
- Success criteria
|
|
|
|
## Required Outputs
|
|
|
|
Create these files in the current directory:
|
|
|
|
### 1. PROMPT.md
|
|
Transform the PRD into Ralph development instructions:
|
|
```markdown
|
|
# Ralph Development Instructions
|
|
|
|
## Context
|
|
You are Ralph, an autonomous AI development agent working on a [PROJECT NAME] project.
|
|
|
|
## Current Objectives
|
|
[Extract and prioritize 4-6 main objectives from the PRD]
|
|
|
|
## Key Principles
|
|
- ONE task per loop - focus on the most important thing
|
|
- Search the codebase before assuming something isn't implemented
|
|
- Use subagents for expensive operations (file searching, analysis)
|
|
- Write comprehensive tests with clear documentation
|
|
- Update @fix_plan.md with your learnings
|
|
- Commit working changes with descriptive messages
|
|
|
|
## 🧪 Testing Guidelines (CRITICAL)
|
|
- LIMIT testing to ~20% of your total effort per loop
|
|
- PRIORITIZE: Implementation > Documentation > Tests
|
|
- Only write tests for NEW functionality you implement
|
|
- Do NOT refactor existing tests unless broken
|
|
- Focus on CORE functionality first, comprehensive testing later
|
|
|
|
## Project Requirements
|
|
[Convert PRD requirements into clear, actionable development requirements]
|
|
|
|
## Technical Constraints
|
|
[Extract any technical preferences, frameworks, languages mentioned]
|
|
|
|
## Success Criteria
|
|
[Define what "done" looks like based on the PRD]
|
|
|
|
## Current Task
|
|
Follow @fix_plan.md and choose the most important item to implement next.
|
|
```
|
|
|
|
### 2. @fix_plan.md
|
|
Convert requirements into a prioritized task list:
|
|
```markdown
|
|
# Ralph Fix Plan
|
|
|
|
## High Priority
|
|
[Extract and convert critical features into actionable tasks]
|
|
|
|
## Medium Priority
|
|
[Secondary features and enhancements]
|
|
|
|
## Low Priority
|
|
[Nice-to-have features and optimizations]
|
|
|
|
## Completed
|
|
- [x] Project initialization
|
|
|
|
## Notes
|
|
[Any important context from the original PRD]
|
|
```
|
|
|
|
### 3. specs/requirements.md
|
|
Create detailed technical specifications:
|
|
```markdown
|
|
# Technical Specifications
|
|
|
|
[Convert PRD into detailed technical requirements including:]
|
|
- System architecture requirements
|
|
- Data models and structures
|
|
- API specifications
|
|
- User interface requirements
|
|
- Performance requirements
|
|
- Security considerations
|
|
- Integration requirements
|
|
|
|
[Preserve all technical details from the original PRD]
|
|
```
|
|
|
|
## Instructions
|
|
1. Read and analyze the attached specification file
|
|
2. Create the three files above with content derived from the PRD
|
|
3. Ensure all requirements are captured and properly prioritized
|
|
4. Make the PROMPT.md actionable for autonomous development
|
|
5. Structure @fix_plan.md with clear, implementable tasks
|
|
|
|
PROMPTEOF
|
|
|
|
# Build and execute Claude Code command
|
|
# Modern CLI: Use --output-format json and --allowedTools for structured output
|
|
# Fallback: Standard CLI invocation for older versions
|
|
if [[ "$use_modern_cli" == "true" ]]; then
|
|
# Modern CLI invocation with JSON output and controlled tool permissions
|
|
# Note: --allowedTools permits file operations without user prompts
|
|
if $CLAUDE_CODE_CMD --output-format "$CLAUDE_OUTPUT_FORMAT" < "$CONVERSION_PROMPT_FILE" > "$CONVERSION_OUTPUT_FILE" 2>&1; then
|
|
cli_exit_code=0
|
|
else
|
|
cli_exit_code=$?
|
|
fi
|
|
else
|
|
# Standard CLI invocation (backward compatible)
|
|
if $CLAUDE_CODE_CMD < "$CONVERSION_PROMPT_FILE" > "$CONVERSION_OUTPUT_FILE" 2>&1; then
|
|
cli_exit_code=0
|
|
else
|
|
cli_exit_code=$?
|
|
fi
|
|
fi
|
|
|
|
# Process the response
|
|
local output_format="text"
|
|
local json_parsed=false
|
|
|
|
if [[ -f "$CONVERSION_OUTPUT_FILE" ]]; then
|
|
output_format=$(detect_response_format "$CONVERSION_OUTPUT_FILE")
|
|
|
|
if [[ "$output_format" == "json" ]]; then
|
|
if parse_conversion_response "$CONVERSION_OUTPUT_FILE"; then
|
|
json_parsed=true
|
|
log "INFO" "Parsed JSON response from Claude CLI"
|
|
|
|
# Check for errors in JSON response
|
|
if [[ "$PARSED_HAS_ERRORS" == "true" && "$PARSED_COMPLETION_STATUS" == "failed" ]]; then
|
|
log "ERROR" "PRD conversion failed"
|
|
if [[ -n "$PARSED_ERROR_MESSAGE" ]]; then
|
|
log "ERROR" "Error: $PARSED_ERROR_MESSAGE"
|
|
fi
|
|
if [[ -n "$PARSED_ERROR_CODE" ]]; then
|
|
log "ERROR" "Error code: $PARSED_ERROR_CODE"
|
|
fi
|
|
rm -f "$CONVERSION_PROMPT_FILE" "$CONVERSION_OUTPUT_FILE"
|
|
exit 1
|
|
fi
|
|
|
|
# Log session ID if available (for potential continuation)
|
|
if [[ -n "$PARSED_SESSION_ID" && "$PARSED_SESSION_ID" != "null" ]]; then
|
|
log "INFO" "Session ID: $PARSED_SESSION_ID"
|
|
fi
|
|
|
|
# Log files changed from metadata
|
|
if [[ -n "$PARSED_FILES_CHANGED" && "$PARSED_FILES_CHANGED" != "0" ]]; then
|
|
log "INFO" "Files changed: $PARSED_FILES_CHANGED"
|
|
fi
|
|
fi
|
|
fi
|
|
fi
|
|
|
|
# Check CLI exit code
|
|
if [[ $cli_exit_code -ne 0 ]]; then
|
|
log "ERROR" "PRD conversion failed (exit code: $cli_exit_code)"
|
|
rm -f "$CONVERSION_PROMPT_FILE" "$CONVERSION_OUTPUT_FILE"
|
|
exit 1
|
|
fi
|
|
|
|
log "SUCCESS" "PRD conversion completed"
|
|
|
|
# Clean up temp files
|
|
rm -f "$CONVERSION_PROMPT_FILE" "$CONVERSION_OUTPUT_FILE"
|
|
|
|
# Verify files were created
|
|
local missing_files=()
|
|
local created_files=()
|
|
|
|
if [[ -f "PROMPT.md" ]]; then
|
|
created_files+=("PROMPT.md")
|
|
else
|
|
missing_files+=("PROMPT.md")
|
|
fi
|
|
|
|
if [[ -f "@fix_plan.md" ]]; then
|
|
created_files+=("@fix_plan.md")
|
|
else
|
|
missing_files+=("@fix_plan.md")
|
|
fi
|
|
|
|
if [[ -f "specs/requirements.md" ]]; then
|
|
created_files+=("specs/requirements.md")
|
|
else
|
|
missing_files+=("specs/requirements.md")
|
|
fi
|
|
|
|
# Report created files
|
|
if [[ ${#created_files[@]} -gt 0 ]]; then
|
|
log "INFO" "Created files: ${created_files[*]}"
|
|
fi
|
|
|
|
# Report and handle missing files
|
|
if [[ ${#missing_files[@]} -ne 0 ]]; then
|
|
log "WARN" "Some files were not created: ${missing_files[*]}"
|
|
|
|
# If JSON parsing provided missing files info, use that for better feedback
|
|
if [[ "$json_parsed" == "true" && -n "$PARSED_MISSING_FILES" && "$PARSED_MISSING_FILES" != "[]" ]]; then
|
|
log "INFO" "Missing files reported by Claude: $PARSED_MISSING_FILES"
|
|
fi
|
|
|
|
log "INFO" "You may need to create these files manually or run the conversion again"
|
|
fi
|
|
}
|
|
|
|
# Main function
|
|
main() {
|
|
local source_file="$1"
|
|
local project_name="$2"
|
|
|
|
# Validate arguments
|
|
if [[ -z "$source_file" ]]; then
|
|
log "ERROR" "Source file is required"
|
|
show_help
|
|
exit 1
|
|
fi
|
|
|
|
if [[ ! -f "$source_file" ]]; then
|
|
log "ERROR" "Source file does not exist: $source_file"
|
|
exit 1
|
|
fi
|
|
|
|
# Default project name from filename
|
|
if [[ -z "$project_name" ]]; then
|
|
project_name=$(basename "$source_file" | sed 's/\.[^.]*$//')
|
|
fi
|
|
|
|
log "INFO" "Converting PRD: $source_file"
|
|
log "INFO" "Project name: $project_name"
|
|
|
|
check_dependencies
|
|
|
|
# Create project directory
|
|
log "INFO" "Creating Ralph project: $project_name"
|
|
ralph-setup "$project_name"
|
|
cd "$project_name"
|
|
|
|
# Copy source file to project
|
|
cp "../$source_file" .
|
|
|
|
# Run conversion
|
|
convert_prd "$source_file" "$project_name"
|
|
|
|
log "SUCCESS" "🎉 PRD imported successfully!"
|
|
echo ""
|
|
echo "Next steps:"
|
|
echo " 1. Review and edit the generated files:"
|
|
echo " - PROMPT.md (Ralph instructions)"
|
|
echo " - @fix_plan.md (task priorities)"
|
|
echo " - specs/requirements.md (technical specs)"
|
|
echo " 2. Start autonomous development:"
|
|
echo " ralph --monitor"
|
|
echo ""
|
|
echo "Project created in: $(pwd)"
|
|
}
|
|
|
|
# Handle command line arguments
|
|
case "${1:-}" in
|
|
-h|--help|"")
|
|
show_help
|
|
exit 0
|
|
;;
|
|
*)
|
|
main "$@"
|
|
;;
|
|
esac |