its-consulting/ralph-claude-code
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ralph-claude-code/ralph_import.sh
Test User 1c9059b902 fix(import): address additional code review feedback 
- Convert CLAUDE_ALLOWED_TOOLS to bash array for proper quoting
- Use array expansion "${CLAUDE_ALLOWED_TOOLS[@]}" in CLI invocation
- Default empty version components to 0 (handles "2.1" style versions)
- Add stderr_file cleanup in JSON error path
- Add type validation for PARSED_FILES_CREATED before array iteration
- Check for empty file names in JSON array iteration
- Fix stale test counts in README.md (165 → 276, 8 → 11 test files)
2026-01-10 11:38:43 -07:00

569 lines
No EOL
18 KiB
Bash
Executable file
Raw Blame History

#!/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"
# Use bash array for proper quoting of each tool argument
declare -a 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)
# Use grep to find first non-whitespace character (handles leading whitespace)
local first_char=$(grep -m1 -o '[^[:space:]]' "$output_file" 2>/dev/null)
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
# Uses numeric comparison for proper semantic versioning
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
# Numeric semantic version comparison
# Split versions into major.minor.patch components
local ver_major ver_minor ver_patch
local min_major min_minor min_patch
IFS='.' read -r ver_major ver_minor ver_patch <<< "$version"
IFS='.' read -r min_major min_minor min_patch <<< "$CLAUDE_MIN_VERSION"
# Default empty components to 0 (handles versions like "2.1" without patch)
ver_major=${ver_major:-0}
ver_minor=${ver_minor:-0}
ver_patch=${ver_patch:-0}
min_major=${min_major:-0}
min_minor=${min_minor:-0}
min_patch=${min_patch:-0}
# Compare major version
if [[ $ver_major -lt $min_major ]]; then
log "WARN" "Claude Code CLI version $version is below recommended $CLAUDE_MIN_VERSION"
return 1
elif [[ $ver_major -gt $min_major ]]; then
return 0
fi
# Major equal, compare minor version
if [[ $ver_minor -lt $min_minor ]]; then
log "WARN" "Claude Code CLI version $version is below recommended $CLAUDE_MIN_VERSION"
return 1
elif [[ $ver_minor -gt $min_minor ]]; then
return 0
fi
# Minor equal, compare patch version
if [[ $ver_patch -lt $min_patch ]]; 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
# Append the PRD source content to the conversion prompt
local source_basename
source_basename=$(basename "$source_file")
if [[ -f "$source_file" ]]; then
echo "" >> "$CONVERSION_PROMPT_FILE"
echo "---" >> "$CONVERSION_PROMPT_FILE"
echo "" >> "$CONVERSION_PROMPT_FILE"
echo "## Source PRD File: $source_basename" >> "$CONVERSION_PROMPT_FILE"
echo "" >> "$CONVERSION_PROMPT_FILE"
cat "$source_file" >> "$CONVERSION_PROMPT_FILE"
else
log "ERROR" "Source file not found: $source_file"
rm -f "$CONVERSION_PROMPT_FILE"
exit 1
fi
# Build and execute Claude Code command
# Modern CLI: Use --output-format json and --allowedTools for structured output
# Fallback: Standard CLI invocation for older versions
# Note: stderr is written to separate file to avoid corrupting JSON output
local stderr_file="${CONVERSION_OUTPUT_FILE}.err"
if [[ "$use_modern_cli" == "true" ]]; then
# Modern CLI invocation with JSON output and controlled tool permissions
# --allowedTools permits file operations without user prompts
# Array expansion preserves quoting for each tool argument
if $CLAUDE_CODE_CMD --output-format "$CLAUDE_OUTPUT_FORMAT" --allowedTools "${CLAUDE_ALLOWED_TOOLS[@]}" < "$CONVERSION_PROMPT_FILE" > "$CONVERSION_OUTPUT_FILE" 2> "$stderr_file"; 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> "$stderr_file"; then
cli_exit_code=0
else
cli_exit_code=$?
fi
fi
# Log stderr if there was any (for debugging)
if [[ -s "$stderr_file" ]]; then
log "WARN" "CLI stderr output detected (see $stderr_file)"
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" "$stderr_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" "$stderr_file"
exit 1
fi
# Use PARSED_RESULT for success message if available
if [[ "$json_parsed" == "true" && -n "$PARSED_RESULT" && "$PARSED_RESULT" != "null" ]]; then
log "SUCCESS" "PRD conversion completed: $PARSED_RESULT"
else
log "SUCCESS" "PRD conversion completed"
fi
# Clean up temp files
rm -f "$CONVERSION_PROMPT_FILE" "$CONVERSION_OUTPUT_FILE" "$stderr_file"
# Verify files were created
# Use PARSED_FILES_CREATED from JSON if available, otherwise check filesystem
local missing_files=()
local created_files=()
local expected_files=("PROMPT.md" "@fix_plan.md" "specs/requirements.md")
# If JSON provided files_created, use that to inform verification
if [[ "$json_parsed" == "true" && -n "$PARSED_FILES_CREATED" && "$PARSED_FILES_CREATED" != "[]" ]]; then
# Validate that PARSED_FILES_CREATED is a valid JSON array before iteration
local is_array
is_array=$(echo "$PARSED_FILES_CREATED" | jq -e 'type == "array"' 2>/dev/null)
if [[ "$is_array" == "true" ]]; then
# Parse JSON array and verify each file exists
local json_files
json_files=$(echo "$PARSED_FILES_CREATED" | jq -r '.[]' 2>/dev/null)
if [[ -n "$json_files" ]]; then
while IFS= read -r file; do
if [[ -n "$file" && -f "$file" ]]; then
created_files+=("$file")
elif [[ -n "$file" ]]; then
missing_files+=("$file")
fi
done <<< "$json_files"
fi
fi
fi
# Always verify expected files exist (filesystem is source of truth)
for file in "${expected_files[@]}"; do
if [[ -f "$file" ]]; then
# Add to created_files if not already there
if [[ ! " ${created_files[*]} " =~ " ${file} " ]]; then
created_files+=("$file")
fi
else
# Add to missing_files if not already there
if [[ ! " ${missing_files[*]} " =~ " ${file} " ]]; then
missing_files+=("$file")
fi
fi
done
# 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
Reference in a new issue View git blame Copy permalink