ralph-tool 1.0.0

package/scripts/postinstall.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// ── Make all bash scripts executable ──
+
+const scriptsDir = path.join(__dirname);
+const helpersDir = path.join(__dirname, '..', 'helpers');
+
+function makeExecutable(dir) {
+  if (!fs.existsSync(dir)) return;
+  const files = fs.readdirSync(dir);
+  for (const file of files) {
+    if (file.endsWith('.sh')) {
+      try {
+        fs.chmodSync(path.join(dir, file), '755');
+      } catch (e) {}
+    }
+  }
+}
+
+makeExecutable(scriptsDir);
+makeExecutable(helpersDir);
+
+// ── Dependency checks ──
+
+const platform = process.platform; // 'darwin' | 'linux'
+
+function hasBin(name) {
+  try {
+    execSync(`command -v ${name}`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function tryInstall(name, { brew, apt, npm: npmPkg } = {}) {
+  // Try brew on macOS
+  if (platform === 'darwin' && brew && hasBin('brew')) {
+    try {
+      console.log(`  Installing ${name} via brew...`);
+      execSync(`brew install ${brew}`, { stdio: 'inherit' });
+      return true;
+    } catch { return false; }
+  }
+  // Try apt on Linux
+  if (platform === 'linux' && apt && hasBin('apt-get')) {
+    try {
+      console.log(`  Installing ${name} via apt...`);
+      execSync(`sudo apt-get install -y ${apt}`, { stdio: 'inherit' });
+      return true;
+    } catch { return false; }
+  }
+  // Try npm
+  if (npmPkg) {
+    try {
+      console.log(`  Installing ${name} via npm...`);
+      execSync(`npm install -g ${npmPkg}`, { stdio: 'inherit' });
+      return true;
+    } catch { return false; }
+  }
+  return false;
+}
+
+// Dependencies: what ralph needs on the host for `ralph loop`
+const deps = [
+  {
+    bin: 'jq',
+    label: 'jq (JSON processor)',
+    required: true,
+    install: { brew: 'jq', apt: 'jq' },
+    manual: 'brew install jq  OR  apt-get install jq',
+  },
+  {
+    bin: 'bc',
+    label: 'bc (calculator)',
+    required: true,
+    install: { brew: 'bc', apt: 'bc' },
+    manual: 'brew install bc  OR  apt-get install bc',
+  },
+  {
+    bin: 'claude',
+    label: 'Claude Code CLI',
+    required: true,
+    install: { npm: '@anthropic-ai/claude-code' },
+    manual: 'npm install -g @anthropic-ai/claude-code',
+  },
+  {
+    bin: 'gh',
+    label: 'GitHub CLI (for PR features)',
+    required: false,
+    install: { brew: 'gh', apt: 'gh' },
+    manual: 'brew install gh  OR  https://cli.github.com',
+  },
+];
+
+console.log('');
+console.log('Checking dependencies...');
+console.log('');
+
+const missing = [];
+
+for (const dep of deps) {
+  if (hasBin(dep.bin)) {
+    console.log(`  ✓ ${dep.label}`);
+  } else {
+    console.log(`  ✗ ${dep.label} — not found, attempting install...`);
+    const installed = tryInstall(dep.bin, dep.install);
+    if (installed && hasBin(dep.bin)) {
+      console.log(`  ✓ ${dep.label} — installed`);
+    } else {
+      missing.push(dep);
+    }
+  }
+}
+
+console.log('');
+
+if (missing.length > 0) {
+  const required = missing.filter(d => d.required);
+  const optional = missing.filter(d => !d.required);
+
+  if (required.length > 0) {
+    console.log('⚠  Missing required dependencies (ralph loop will not work without these):');
+    console.log('');
+    for (const dep of required) {
+      console.log(`   ${dep.label}`);
+      console.log(`     → ${dep.manual}`);
+    }
+    console.log('');
+  }
+
+  if (optional.length > 0) {
+    console.log('ℹ  Missing optional dependencies:');
+    console.log('');
+    for (const dep of optional) {
+      console.log(`   ${dep.label}`);
+      console.log(`     → ${dep.manual}`);
+    }
+    console.log('');
+  }
+}
+
+console.log('Ralph tool installed successfully!');
+console.log('');
+console.log('Usage:');
+console.log('  ralph init     - Initialize Ralph in current directory');
+console.log('  ralph start    - Start Ralph in Docker sandbox');
+console.log('  ralph loop     - Run Ralph loop directly');
+console.log('  ralph status   - Check task status');
+console.log('  ralph --help   - Show all commands');
+console.log('');

package/scripts/review.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Ralph Review - PR Summary & Merge Automation
+# Environment: PROJECT_RALPH_DIR
+
+PROJECT_RALPH_DIR="${PROJECT_RALPH_DIR:?PROJECT_RALPH_DIR not set}"
+PROMPT_FILE="${PROJECT_RALPH_DIR}/config/pr-review-prompt.md"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+LIGHT_BLUE='\033[1;36m'
+NC='\033[0m'
+
+echo ""
+echo -e "${LIGHT_BLUE}Ralph Review - PR Summary & Merge${NC}"
+echo ""
+
+# Verify prompt file exists
+if [[ ! -f "$PROMPT_FILE" ]]; then
+    echo -e "${RED}Error: Prompt file not found at ${PROMPT_FILE}${NC}"
+    exit 1
+fi
+
+# 1. Get latest open PR
+echo "[1/5] Checking for open PRs..."
+PR_JSON=$(gh pr list --state open --limit 1 --json number,title,body)
+PR_NUMBER=$(echo "$PR_JSON" | jq -r '.[0].number // empty')
+
+if [[ -z "$PR_NUMBER" ]]; then
+    echo -e "${RED}No open PRs found${NC}"
+    exit 1
+fi
+
+PR_TITLE=$(echo "$PR_JSON" | jq -r '.[0].title')
+PR_BODY=$(echo "$PR_JSON" | jq -r '.[0].body')
+echo -e "  ${GREEN}✓${NC} Found PR #${PR_NUMBER}: ${PR_TITLE}"
+
+# 2. Get PR diff
+echo "[2/5] Fetching PR diff..."
+PR_DIFF=$(gh pr diff "$PR_NUMBER")
+echo -e "  ${GREEN}✓${NC} Diff fetched"
+
+# 3. Generate summary via Claude
+echo "[3/5] Generating PR summary via Claude..."
+PR_CONTEXT="PR #${PR_NUMBER}: ${PR_TITLE}
+
+## PR Description
+${PR_BODY}
+
+## Diff
+${PR_DIFF}"
+
+PROMPT=$(cat "$PROMPT_FILE")
+
+# Call Claude and capture output
+SUMMARY=$(echo "$PR_CONTEXT" | claude --dangerously-skip-permissions --print -p "$PROMPT" 2>&1) || {
+    echo -e "${RED}Claude failed to generate summary${NC}"
+    exit 1
+}
+
+echo ""
+echo "==============================================================================="
+echo -e "${LIGHT_BLUE}PR #${PR_NUMBER} Summary${NC}"
+echo "==============================================================================="
+echo ""
+echo "$SUMMARY"
+echo ""
+echo "==============================================================================="
+echo ""
+
+# 4. Merge PR
+echo "[4/5] Merging PR #${PR_NUMBER}..."
+if ! gh pr merge "$PR_NUMBER" --squash --delete-branch; then
+    echo -e "${RED}Merge failed - check for conflicts${NC}"
+    exit 1
+fi
+echo -e "  ${GREEN}✓${NC} PR merged and branch deleted"
+
+# 5. Update local
+echo "[5/5] Updating local main branch..."
+git checkout main
+git pull
+echo -e "  ${GREEN}✓${NC} Local main updated"
+
+echo ""
+echo -e "${GREEN}Review complete!${NC}"
+echo ""

package/scripts/sandbox.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Open interactive Docker sandbox environment
+# Environment: RALPH_HOME, PROJECT_DIR
+
+set -euo pipefail
+
+RALPH_HOME="${RALPH_HOME:?RALPH_HOME not set}"
+PROJECT_DIR="${PROJECT_DIR:?PROJECT_DIR not set}"
+
+# Run interactive bash in Docker container
+docker compose -f "${RALPH_HOME}/docker-compose.yaml" run --rm \
+    -v "${PROJECT_DIR}:/workspace:rw" \
+    -e PROJECT_DIR=/workspace \
+    -e PROJECT_RALPH_DIR=/workspace/.ralph \
+    ai bash

package/scripts/start.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Combined script to start sandbox and run Ralph loop inside container
+# Environment: RALPH_HOME, PROJECT_DIR, PROJECT_RALPH_DIR
+
+set -euo pipefail
+
+MAX_ITERS="${1:-6}"
+MODEL="${2:-}"
+
+RALPH_HOME="${RALPH_HOME:?RALPH_HOME not set}"
+PROJECT_DIR="${PROJECT_DIR:?PROJECT_DIR not set}"
+
+# Build ralph command with optional model parameter
+RALPH_CMD="ralph loop"
+[[ -n "$MODEL" ]] && RALPH_CMD="$RALPH_CMD --model $MODEL"
+RALPH_CMD="$RALPH_CMD --max ${MAX_ITERS}"
+[[ "${RALPH_LOCAL:-}" == "1" ]] && RALPH_CMD="$RALPH_CMD --local"
+
+# Run the ralph loop command inside the Docker container
+# Mount the project directory to /workspace
+docker compose -f "${RALPH_HOME}/docker-compose.yaml" run --rm \
+    -v "${PROJECT_DIR}:/workspace:rw" \
+    -e PROJECT_DIR=/workspace \
+    -e PROJECT_RALPH_DIR=/workspace/.ralph \
+    ai bash -c "${RALPH_CMD}"

package/scripts/status.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Ralph Status - Concise status for agent consumption
+# Environment: PROJECT_RALPH_DIR
+
+PROJECT_RALPH_DIR="${PROJECT_RALPH_DIR:?PROJECT_RALPH_DIR not set}"
+PRD_FILE="${PROJECT_RALPH_DIR}/tasks/prd.json"
+
+# Color support (only if TTY)
+if [[ -t 1 ]]; then
+  BOLD="\033[1m"
+  CYAN="\033[36m"
+  GREEN="\033[32m"
+  YELLOW="\033[33m"
+  BLUE="\033[34m"
+  DIM="\033[2m"
+  RESET="\033[0m"
+else
+  BOLD=""
+  CYAN=""
+  GREEN=""
+  YELLOW=""
+  BLUE=""
+  DIM=""
+  RESET=""
+fi
+
+# Check if prd.json exists
+if [[ ! -f "$PRD_FILE" ]]; then
+    echo "ERROR: prd.json not found"
+    exit 1
+fi
+
+# Find current feature (first incomplete feature)
+CURRENT_FEATURE_ID=$(jq -r '.features[] | select(.feature_completed == false) | .id' "$PRD_FILE" 2>/dev/null | head -1)
+
+if [[ -z "$CURRENT_FEATURE_ID" ]]; then
+    echo "All features completed!"
+    echo ""
+    jq -r '.features[] | "  [DONE] \(.id): \(.name)"' "$PRD_FILE" 2>/dev/null
+    exit 0
+fi
+
+# Get current feature details
+CURRENT_FEATURE_NAME=$(jq -r --arg id "$CURRENT_FEATURE_ID" '.features[] | select(.id == $id) | .name' "$PRD_FILE" 2>/dev/null)
+CURRENT_FEATURE_NUM=$(jq -r --arg id "$CURRENT_FEATURE_ID" '[.features[].id] | to_entries | .[] | select(.value == $id) | .key + 1' "$PRD_FILE" 2>/dev/null)
+
+# Count tasks in current feature
+TOTAL_TASKS=$(jq --arg id "$CURRENT_FEATURE_ID" '.features[] | select(.id == $id) | .tasks | length' "$PRD_FILE" 2>/dev/null)
+COMPLETED_TASKS=$(jq --arg id "$CURRENT_FEATURE_ID" '.features[] | select(.id == $id) | [.tasks[] | select(.completed == true)] | length' "$PRD_FILE" 2>/dev/null)
+PENDING_TASKS=$((TOTAL_TASKS - COMPLETED_TASKS))
+
+# Count total features
+TOTAL_FEATURES=$(jq '.features | length' "$PRD_FILE" 2>/dev/null)
+COMPLETED_FEATURES=$(jq '[.features[] | select(.feature_completed == true)] | length' "$PRD_FILE" 2>/dev/null)
+
+# Calculate border width
+header="Current Feature: $CURRENT_FEATURE_NAME (Feature $CURRENT_FEATURE_NUM of $TOTAL_FEATURES)"
+header_len=${#header}
+border_len=$((header_len > 60 ? header_len + 4 : 64))
+
+# Build border
+border="╔"
+for ((i=0; i<border_len-2; i++)); do border+="═"; done
+border+="╗"
+
+bottom_border="╚"
+for ((i=0; i<border_len-2; i++)); do bottom_border+="═"; done
+bottom_border+="╝"
+
+# Human-readable output
+printf "%b\n" "${BOLD}${CYAN}${border}${RESET}"
+printf "%b\n" "${BOLD}${CYAN}║${RESET} ${BOLD}Current Feature:${RESET} ${YELLOW}${CURRENT_FEATURE_NAME}${RESET} ${DIM}(Feature ${CURRENT_FEATURE_NUM} of ${TOTAL_FEATURES})${RESET}"
+printf "%b\n" "${BOLD}${CYAN}║${RESET} ${BOLD}Status:${RESET} ${GREEN}${COMPLETED_TASKS}${RESET}/${TOTAL_TASKS} tasks completed, ${YELLOW}${PENDING_TASKS}${RESET} pending"
+printf "%b\n" "${BOLD}${CYAN}${bottom_border}${RESET}"
+echo ""
+
+# List all tasks in current feature
+printf "%b\n" "${BOLD}Tasks:${RESET}"
+jq -r --arg id "$CURRENT_FEATURE_ID" '.features[] | select(.id == $id) | .tasks[] | "  \(if .completed then "[DONE]" else "[TODO]" end) \(.id): \(.name)"' "$PRD_FILE" 2>/dev/null | while IFS= read -r line; do
+    if [[ "$line" =~ ^\s*\[DONE\] ]]; then
+        printf "%b\n" "${DIM}${line}${RESET}"
+    else
+        printf "%b\n" "${BOLD}${line}${RESET}"
+    fi
+done
+
+# Show next incomplete task details
+echo ""
+NEXT_TASK=$(jq -r --arg id "$CURRENT_FEATURE_ID" '.features[] | select(.id == $id) | .tasks[] | select(.completed == false) | .id' "$PRD_FILE" 2>/dev/null | head -1)
+if [[ -n "$NEXT_TASK" ]]; then
+    printf "%b\n" "${BOLD}${BLUE}Next task: ${NEXT_TASK}${RESET}"
+    jq -r --arg fid "$CURRENT_FEATURE_ID" --arg tid "$NEXT_TASK" '.features[] | select(.id == $fid) | .tasks[] | select(.id == $tid) | "  Name: \(.name)\n  Spec: \(.specFile // "none")\n  Requirements: \(.requirements | join(", "))"' "$PRD_FILE" 2>/dev/null
+else
+    printf "%b\n" "${BOLD}${GREEN}All tasks in current feature completed - ready for feature completion!${RESET}"
+fi
+
+# Show feature overview
+echo ""
+printf "%b\n" "${BOLD}All Features:${RESET}"
+jq -r '.features[] | "  \(if .feature_completed then "[DONE]" else "[TODO]" end) \(.id): \(.name)"' "$PRD_FILE" 2>/dev/null | while IFS= read -r line; do
+    if [[ "$line" =~ ^\s*\[DONE\] ]]; then
+        printf "%b\n" "${DIM}${line}${RESET}"
+    else
+        printf "%b\n" "${BOLD}${line}${RESET}"
+    fi
+done

package/templates/AGENT.md

@@ -0,0 +1,27 @@
+# Ralph Agent Knowledge Base
+
+This file contains persistent learnings and patterns discovered across Ralph iterations.
+Each iteration should update this file with new patterns, gotchas, and architectural insights
+only if something new and relevant has been discovered.
+
+**Progress Management:**
+- Within feature: progress.txt accumulates task summaries
+- Between features: progress.txt archives to `logs/progress/{feature-name}-progress-{timestamp}.txt`
+- AGENT.md persists across all features (never cleared)
+- NOTE: Do not create explainer documents or other documentation unless specifically asked to.
+
+## CRITICAL: Code Reuse Philosophy
+
+**NEVER ASSUME FUNCTIONALITY DOESN'T EXIST**
+- Always search for existing implementations before creating new ones
+- Check for utility functions that might already do what you need
+- Look for similar patterns in other parts of the codebase
+- Reuse existing services, stores, and API endpoints when possible
+
+## Known Patterns
+
+<!-- Add project-specific patterns here as you discover them -->
+
+## Known Gotchas
+
+<!-- Add project-specific gotchas here as you discover them -->

package/templates/feature-spec-template.md

@@ -0,0 +1,115 @@
+# Feature Spec: [Feature Name]
+
+## Goal
+
+**What user-visible change should exist when done?**
+
+[1-2 lines describing the user-facing outcome]
+
+**Success Criteria:**
+- [How you'll know it worked - specific requirement that must be met]
+
+
+## Non-goals
+
+**Explicitly list what NOT to do (prevents scope creep):**
+- [Out of scope item 1]
+- [Out of scope item 2]
+
+---
+
+## Implementation Tasks
+
+**Subtask 1: [Layer/Component Name]**
+- **Requirements:**
+  - [Specific requirement 1]
+  - [Specific requirement 2]
+- **Done when:** [Completion criteria]
+- **Files:** [List of files to modify/create]
+
+**Subtask 2: [Layer/Component Name]**
+- **Requirements:**
+  - [Specific requirement 1]
+  - [Specific requirement 2]
+- **Done when:** [Completion criteria]
+- **Files:** [List of files to modify/create]
+
+---
+
+## Current State
+
+**Where this lives:**
+- Files/folders: `[path/to/relevant/files]`
+- Related domains: `[domain1, domain2]`
+
+**How it works today:**
+- [Brief description of current behavior]
+
+---
+
+## Proposed Behavior
+
+**Write as bullet rules, not prose:**
+
+**Primary flow:**
+- If [condition X], then [action Y]
+- If [condition Z], then [action W]
+
+**Edge cases:**
+- When [edge case 1], [behavior]
+- Error handling: [what happens on errors]
+
+---
+
+## UX / UI (if relevant)
+
+**Screens/components affected:**
+- `[component/path/file.tsx]` - [what changes]
+
+**States to handle:**
+- Empty state: [what shows when no data]
+- Loading state: [what shows while loading]
+- Error state: [what shows on error]
+- Success state: [what shows on success]
+
+---
+
+## Data + APIs (if relevant)
+
+**API endpoints:**
+- `POST /api/[path]` - [description]
+  - Request: `{ [field]: [type], ... }`
+  - Response: `{ [field]: [type], ... }`
+
+---
+
+## Files to Touch
+
+**Most likely files (Ralph should start here):**
+- `path/to/file1.ts`
+- `path/to/file2.tsx`
+
+---
+
+## Patterns and helpers
+
+Reuse existing files where possible. Follow existing patterns in the project.
+
+---
+
+## Notes
+
+**Additional context for Ralph:**
+- [Any special considerations]
+- [Dependencies on other features]
+- [Known gotchas]
+
+---
+
+## How to Use This Template
+
+1. Fill in all sections with specific requirements
+2. Organize subtasks logically
+3. Be specific in requirements and completion criteria
+4. Omit sections that don't apply
+5. Update prd.json with the task linking to this spec file

package/templates/plan-cleanup-prompt.md

@@ -0,0 +1,61 @@
+# Ralph Plan Cleanup - REVIEW & CONSOLIDATION MODE
+
+## YOUR ROLE
+
+You are reviewing and cleaning up the planning output from previous iterations. Your job is to ensure quality, remove redundancy, fix ordering, and verify complete vision coverage.
+
+## Instructions
+
+### Step 1: Read Everything
+
+Read ALL of these files:
+1. `.ralph/config/vision.md` — The project vision
+2. `.ralph/config/AGENT.md` — Accumulated learnings
+3. `.ralph/tasks/prd.json` — All planned features and tasks
+4. ALL spec files in `.ralph/tasks/1_new_tasks/` — Read every spec file referenced in prd.json
+5. `.ralph/tasks/progress.txt` — Planning history
+
+### Step 2: Audit Against Vision
+
+For each section/area of the vision:
+- Is there a corresponding feature in prd.json?
+- Are the tasks specific enough for automated implementation?
+- Do the spec files have actionable details (file paths, component names, behavior rules)?
+
+Flag any gaps — areas of the vision not yet covered by features.
+
+### Step 3: Clean Up
+
+Review all features and tasks for:
+- **Duplicates**: Merge features/tasks that overlap or cover the same ground
+- **Irrelevant tasks**: Remove tasks that don't align with the current vision
+- **Ordering issues**: Reorder features so dependencies come first (e.g., data models before UI)
+- **Spec quality**: Improve specs that are too vague for implementation — add specifics
+- **Task granularity**: Split tasks that are too large (multi-day work), merge tasks that are too small (trivial one-liners)
+
+Make changes directly to prd.json and spec files.
+
+### Step 4: Update Progress
+
+Append to `.ralph/tasks/progress.txt`:
+- What was cleaned up, reordered, or removed
+- Any gaps identified that still need planning
+
+Update `.ralph/config/AGENT.md` with any new learnings.
+
+### Step 5: Completion Check
+
+After cleanup, assess vision coverage:
+- If ALL areas of the vision have detailed features, well-ordered tasks, and actionable spec files: output `<promise>COMPLETE</promise>`
+- If there are still gaps: output "Cleanup complete. Gaps remaining: [list areas]. Exiting for next iteration."
+
+EXIT IMMEDIATELY after this assessment.
+
+## CLEANUP RULES
+
+1. **BE RUTHLESS**: Remove tasks that don't serve the vision
+2. **PRESERVE INTENT**: When merging/reordering, keep the original requirements intact
+3. **NO NEW FEATURES**: Only clean up existing plans — creating new features is for the plan prompt
+4. **FIX ORDERING**: Features should flow naturally for sequential implementation
+5. **IMPROVE SPECS**: If a spec is too vague, add details from your codebase analysis
+6. **ALWAYS EXIT**: After cleanup, exit for fresh iteration