agentic-loop 1.0.0

package/ralph/checks/check-fastapi-responses.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""
+Check that FastAPI endpoints have Pydantic response models defined.
+Ensures Swagger/OpenAPI docs show proper response schemas.
+
+Usage: python check-fastapi-responses.py [directory]
+
+Exit codes:
+  0 - All endpoints have response models
+  1 - Some endpoints missing response models
+"""
+
+import ast
+import sys
+from pathlib import Path
+from typing import NamedTuple
+
+
+class EndpointIssue(NamedTuple):
+    file: str
+    line: int
+    method: str
+    path: str
+    issue: str
+
+
+def check_file(filepath: Path) -> list[EndpointIssue]:
+    """Check a single Python file for FastAPI endpoints without response models."""
+    issues = []
+
+    try:
+        content = filepath.read_text()
+        tree = ast.parse(content)
+    except (SyntaxError, UnicodeDecodeError):
+        return issues
+
+    # HTTP methods that should have response models
+    http_methods = {'get', 'post', 'put', 'patch', 'delete'}
+
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+
+        # Check decorators for FastAPI route decorators
+        for decorator in node.decorator_list:
+            # Handle @router.get("/path") or @app.get("/path")
+            if isinstance(decorator, ast.Call):
+                if isinstance(decorator.func, ast.Attribute):
+                    method = decorator.func.attr
+                    if method not in http_methods:
+                        continue
+
+                    # Get the path from first argument
+                    path = "unknown"
+                    if decorator.args and isinstance(decorator.args[0], ast.Constant):
+                        path = decorator.args[0].value
+
+                    # Check for response_model in keyword arguments
+                    has_response_model = any(
+                        kw.arg == 'response_model'
+                        for kw in decorator.keywords
+                    )
+
+                    # Check for return type annotation
+                    has_return_annotation = node.returns is not None
+
+                    # Check if return annotation is None or missing
+                    is_none_return = (
+                        isinstance(node.returns, ast.Constant) and
+                        node.returns.value is None
+                    )
+
+                    if not has_response_model and (not has_return_annotation or is_none_return):
+                        # Skip certain common patterns that don't need response models
+                        if method == 'delete' and path.endswith('}'):
+                            continue  # DELETE /items/{id} often returns nothing
+
+                        issues.append(EndpointIssue(
+                            file=str(filepath),
+                            line=node.lineno,
+                            method=method.upper(),
+                            path=path,
+                            issue="Missing response_model or return type annotation"
+                        ))
+
+    return issues
+
+
+def check_directory(directory: Path) -> list[EndpointIssue]:
+    """Check all Python files in directory for FastAPI response model issues."""
+    all_issues = []
+
+    # Common patterns for API files
+    patterns = [
+        '**/router*.py',
+        '**/routes*.py',
+        '**/api*.py',
+        '**/endpoints*.py',
+        '**/views*.py',
+    ]
+
+    checked_files = set()
+
+    for pattern in patterns:
+        for filepath in directory.glob(pattern):
+            if filepath in checked_files:
+                continue
+            checked_files.add(filepath)
+            all_issues.extend(check_file(filepath))
+
+    # Also check any file with FastAPI imports
+    for filepath in directory.rglob('*.py'):
+        if filepath in checked_files:
+            continue
+        try:
+            content = filepath.read_text()
+            if 'from fastapi' in content or 'import fastapi' in content:
+                if 'APIRouter' in content or '@app.' in content or '@router.' in content:
+                    all_issues.extend(check_file(filepath))
+                    checked_files.add(filepath)
+        except (UnicodeDecodeError, PermissionError):
+            continue
+
+    return all_issues
+
+
+def main():
+    directory = Path(sys.argv[1]) if len(sys.argv) > 1 else Path('.')
+
+    if not directory.exists():
+        print(f"Error: Directory not found: {directory}")
+        sys.exit(1)
+
+    issues = check_directory(directory)
+
+    if not issues:
+        print("✓ All FastAPI endpoints have response models defined")
+        sys.exit(0)
+
+    print(f"Found {len(issues)} endpoint(s) without response models:\n")
+
+    for issue in sorted(issues, key=lambda x: (x.file, x.line)):
+        print(f"  {issue.file}:{issue.line}")
+        print(f"    {issue.method} {issue.path}")
+        print(f"    → {issue.issue}\n")
+
+    print("Fix: Add response_model parameter or return type annotation:")
+    print('  @router.get("/items", response_model=list[ItemSchema])')
+    print("  async def get_items() -> list[ItemSchema]:")
+
+    sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

package/ralph/hooks/hooks-config.json

@@ -0,0 +1,72 @@
+{
+  "_comment": "Copy this 'hooks' section into your ~/.claude/settings.json or .claude/settings.json",
+  "_instructions": "Replace VIBE_PATH with the path to your agentic-loop installation",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "VIBE_PATH/ralph/hooks/protect-prd.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "VIBE_PATH/ralph/hooks/warn-debug.sh",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "VIBE_PATH/ralph/hooks/warn-secrets.sh",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "VIBE_PATH/ralph/hooks/warn-urls.sh",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "VIBE_PATH/ralph/hooks/log-tools.sh",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "VIBE_PATH/ralph/hooks/inject-context.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "VIBE_PATH/ralph/hooks/save-learnings.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/ralph/hooks/inject-context.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# inject-context.sh - Inject signs and recent progress at session start
+# Hook: SessionStart
+
+set -euo pipefail
+
+INPUT=$(cat)
+CWD=$(echo "$INPUT" | jq -r '.cwd // "."')
+RALPH_DIR="$CWD/.ralph"
+
+CONTEXT=""
+
+# Inject signs (learned patterns)
+if [[ -f "$RALPH_DIR/signs.json" ]]; then
+  SIGNS=$(jq -r '.signs[]? | "- [\(.category)] \(.pattern)"' "$RALPH_DIR/signs.json" 2>/dev/null | head -20)
+  if [[ -n "$SIGNS" ]]; then
+    CONTEXT="## Learned Patterns (Signs)\nApply these lessons:\n$SIGNS\n\n"
+  fi
+fi
+
+# Inject recent progress
+if [[ -f "$RALPH_DIR/progress.txt" ]]; then
+  PROGRESS=$(tail -10 "$RALPH_DIR/progress.txt" 2>/dev/null)
+  if [[ -n "$PROGRESS" ]]; then
+    CONTEXT="${CONTEXT}## Recent Progress\n$PROGRESS\n\n"
+  fi
+fi
+
+# Inject last failure context if exists
+if [[ -f "$RALPH_DIR/last_failure.txt" ]]; then
+  FAILURE=$(cat "$RALPH_DIR/last_failure.txt" | head -50)
+  CONTEXT="${CONTEXT}## Previous Failure (FIX THIS)\n$FAILURE\n"
+fi
+
+if [[ -n "$CONTEXT" ]]; then
+  jq -n --arg ctx "$CONTEXT" '{
+    "continue": true,
+    "hookSpecificOutput": {
+      "additionalContext": $ctx
+    }
+  }'
+else
+  echo '{"continue": true}'
+fi

package/ralph/hooks/install.sh

@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+# install.sh - Install Ralph hooks into Claude Code settings
+#
+# Usage: ./install.sh [--global] [--force]
+#   --global: Install to ~/.claude/settings.json (applies to all projects)
+#   --force:  Reinstall even if hooks already configured
+#   Default: Install to .claude/settings.json (project-level)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Parse args
+SETTINGS_FILE=".claude/settings.json"
+FORCE=false
+
+for arg in "$@"; do
+  case $arg in
+    --global)
+      SETTINGS_FILE="$HOME/.claude/settings.json"
+      ;;
+    --force)
+      FORCE=true
+      ;;
+  esac
+done
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+# Auto-install jq if missing
+install_jq() {
+  echo -e "${YELLOW}jq not found, installing...${NC}"
+
+  if [[ "$OSTYPE" == "darwin"* ]]; then
+    # macOS
+    if command -v brew &>/dev/null; then
+      brew install jq
+    else
+      echo -e "${RED}Error: Homebrew not found. Install jq manually:${NC}"
+      echo "  brew install jq"
+      echo "  Or: https://jqlang.github.io/jq/download/"
+      exit 1
+    fi
+  elif command -v apt-get &>/dev/null; then
+    # Debian/Ubuntu
+    sudo apt-get update -qq && sudo apt-get install -y jq
+  elif command -v dnf &>/dev/null; then
+    # Fedora/RHEL 8+
+    sudo dnf install -y jq
+  elif command -v yum &>/dev/null; then
+    # CentOS/RHEL 7
+    sudo yum install -y jq
+  elif command -v pacman &>/dev/null; then
+    # Arch
+    sudo pacman -S --noconfirm jq
+  elif command -v apk &>/dev/null; then
+    # Alpine
+    sudo apk add jq
+  else
+    echo -e "${RED}Error: Could not detect package manager.${NC}"
+    echo "Install jq manually: https://jqlang.github.io/jq/download/"
+    exit 1
+  fi
+
+  echo -e "${GREEN}✓ jq installed${NC}"
+}
+
+# Check for jq, install if missing
+if ! command -v jq &>/dev/null; then
+  install_jq
+fi
+
+echo "Installing Ralph hooks..."
+echo "  Hooks path: $SCRIPT_DIR"
+echo "  Settings: $SETTINGS_FILE"
+echo ""
+
+# Ensure settings directory exists
+mkdir -p "$(dirname "$SETTINGS_FILE")"
+
+# Create settings file if it doesn't exist
+if [[ ! -f "$SETTINGS_FILE" ]]; then
+  echo '{}' > "$SETTINGS_FILE"
+fi
+
+# Check if hooks already configured and valid
+if [[ "$FORCE" != "true" ]] && jq -e '.hooks' "$SETTINGS_FILE" > /dev/null 2>&1; then
+  session_hook=$(jq -r '.hooks.SessionStart[0].hooks[0].command // empty' "$SETTINGS_FILE" 2>/dev/null)
+  stop_hook=$(jq -r '.hooks.Stop[0].hooks[0].command // empty' "$SETTINGS_FILE" 2>/dev/null)
+
+  # All hooks must exist AND point to current script directory
+  if [[ -n "$session_hook" && -x "$session_hook" && -n "$stop_hook" && -x "$stop_hook" ]]; then
+    if [[ "$session_hook" == "$SCRIPT_DIR/"* && "$stop_hook" == "$SCRIPT_DIR/"* ]]; then
+      echo -e "${YELLOW}Hooks already configured and valid.${NC}"
+      echo "Use --force to reinstall."
+      exit 0
+    else
+      echo -e "${YELLOW}Hooks point to different location, updating...${NC}"
+      echo ""
+    fi
+  else
+    echo -e "${YELLOW}Existing hooks are invalid, reinstalling...${NC}"
+    echo ""
+  fi
+fi
+
+# Build hooks config with actual path
+HOOKS_CONFIG=$(cat <<EOF
+{
+  "PreToolUse": [
+    {
+      "matcher": "Edit|Write",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "$SCRIPT_DIR/protect-prd.sh",
+          "timeout": 5
+        }
+      ]
+    }
+  ],
+  "PostToolUse": [
+    {
+      "matcher": "Edit|Write",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "$SCRIPT_DIR/warn-debug.sh",
+          "timeout": 5
+        },
+        {
+          "type": "command",
+          "command": "$SCRIPT_DIR/warn-secrets.sh",
+          "timeout": 5
+        },
+        {
+          "type": "command",
+          "command": "$SCRIPT_DIR/warn-urls.sh",
+          "timeout": 5
+        },
+        {
+          "type": "command",
+          "command": "$SCRIPT_DIR/warn-empty-catch.sh",
+          "timeout": 5
+        }
+      ]
+    },
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "$SCRIPT_DIR/log-tools.sh",
+          "timeout": 3
+        }
+      ]
+    }
+  ],
+  "SessionStart": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "$SCRIPT_DIR/inject-context.sh",
+          "timeout": 5
+        }
+      ]
+    }
+  ],
+  "Stop": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "$SCRIPT_DIR/save-learnings.sh",
+          "timeout": 10
+        }
+      ]
+    }
+  ]
+}
+EOF
+)
+
+# Merge hooks into settings
+CURRENT_SETTINGS=$(cat "$SETTINGS_FILE")
+MERGED=$(echo "$CURRENT_SETTINGS" | jq --argjson hooks "$HOOKS_CONFIG" '.hooks = $hooks')
+
+echo "$MERGED" > "$SETTINGS_FILE"
+
+echo -e "${GREEN}✓ Hooks installed successfully!${NC}"
+echo ""
+echo "Hooks enabled:"
+echo "  • protect-prd.sh      - Blocks edits to prd.json"
+echo "  • warn-debug.sh       - Warns about console.log/debugger"
+echo "  • warn-secrets.sh     - Warns about hardcoded secrets/API keys"
+echo "  • warn-urls.sh        - Warns about hardcoded localhost URLs"
+echo "  • warn-empty-catch.sh - Warns about empty catch blocks"
+echo "  • inject-context.sh   - Loads signs & progress at session start"
+echo "  • save-learnings.sh   - Extracts learnings at session end"
+echo "  • log-tools.sh        - Logs tool usage to .ralph/tool-log.txt"
+echo ""
+echo -e "${YELLOW}Note:${NC} Restart Claude Code for hooks to take effect."

package/ralph/hooks/log-tools.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# log-tools.sh - Log tool usage for debugging and analysis
+# Hook: PostToolUse matcher: "*"
+
+set -euo pipefail
+
+INPUT=$(cat)
+CWD=$(echo "$INPUT" | jq -r '.cwd // "."')
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"')
+RALPH_DIR="$CWD/.ralph"
+
+# Only log if .ralph exists (we're in a Ralph session)
+if [[ -d "$RALPH_DIR" ]]; then
+  TIMESTAMP=$(date '+%H:%M:%S')
+
+  # Extract relevant info based on tool
+  case "$TOOL_NAME" in
+    Read)
+      FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' | sed "s|$CWD/||")
+      echo "[$TIMESTAMP] READ: $FILE" >> "$RALPH_DIR/tool-log.txt"
+      ;;
+    Write)
+      FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' | sed "s|$CWD/||")
+      echo "[$TIMESTAMP] WRITE: $FILE" >> "$RALPH_DIR/tool-log.txt"
+      ;;
+    Edit)
+      FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' | sed "s|$CWD/||")
+      echo "[$TIMESTAMP] EDIT: $FILE" >> "$RALPH_DIR/tool-log.txt"
+      ;;
+    Bash)
+      CMD=$(echo "$INPUT" | jq -r '.tool_input.command // ""' | head -c 80)
+      echo "[$TIMESTAMP] BASH: $CMD" >> "$RALPH_DIR/tool-log.txt"
+      ;;
+    Grep|Glob)
+      PATTERN=$(echo "$INPUT" | jq -r '.tool_input.pattern // ""')
+      echo "[$TIMESTAMP] $TOOL_NAME: $PATTERN" >> "$RALPH_DIR/tool-log.txt"
+      ;;
+    Task)
+      DESC=$(echo "$INPUT" | jq -r '.tool_input.description // ""')
+      echo "[$TIMESTAMP] TASK: $DESC" >> "$RALPH_DIR/tool-log.txt"
+      ;;
+  esac
+fi
+
+echo '{"continue": true}'

package/ralph/hooks/protect-prd.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# protect-prd.sh - Protect prd.json from accidental edits
+# Hook: PreToolUse matcher: "Edit|Write"
+#
+# Allows: /prd, /idea commands (they create .prd-edit-allowed marker)
+# Blocks: Accidental edits during normal coding
+
+set -euo pipefail
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""')
+
+# Check if editing prd.json
+if [[ "$FILE_PATH" == *"prd.json"* ]]; then
+  # Allow if /prd or /idea set the bypass marker
+  if [[ -f ".ralph/.prd-edit-allowed" ]]; then
+    rm -f ".ralph/.prd-edit-allowed"  # One-time use
+    echo '{"continue": true}'
+    exit 0
+  fi
+
+  echo "BLOCKED: prd.json is managed by Ralph. Use /prd or /idea to add stories." >&2
+  exit 2  # Exit code 2 = blocking error
+fi
+
+# Allow all other edits
+echo '{"continue": true}'

package/ralph/hooks/save-learnings.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# save-learnings.sh - Extract potential learnings from session transcript
+# Hook: Stop
+#
+# This hook analyzes the transcript for patterns that might be worth saving as signs.
+# It logs suggestions to .ralph/suggested-signs.txt for human review.
+
+set -euo pipefail
+
+INPUT=$(cat)
+CWD=$(echo "$INPUT" | jq -r '.cwd // "."')
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // ""')
+RALPH_DIR="$CWD/.ralph"
+
+# Ensure .ralph directory exists
+mkdir -p "$RALPH_DIR"
+
+# Log session end
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] Session ended" >> "$RALPH_DIR/progress.txt"
+
+# If transcript exists, analyze for patterns
+if [[ -f "$TRANSCRIPT_PATH" ]]; then
+  # Look for retry patterns (same error appearing multiple times)
+  # Look for "I learned" or "the issue was" phrases
+  # This is a simple heuristic - can be enhanced
+
+  PATTERNS=$(grep -E "(the issue was|I learned|the problem was|fixed by|solution was)" "$TRANSCRIPT_PATH" 2>/dev/null | tail -5 || true)
+
+  if [[ -n "$PATTERNS" ]]; then
+    echo "" >> "$RALPH_DIR/suggested-signs.txt"
+    echo "=== Session $(date '+%Y-%m-%d %H:%M:%S') ===" >> "$RALPH_DIR/suggested-signs.txt"
+    echo "$PATTERNS" >> "$RALPH_DIR/suggested-signs.txt"
+  fi
+fi
+
+echo '{"continue": true}'

package/ralph/hooks/warn-debug.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# warn-debug.sh - Warn about debug statements in written code
+# Hook: PostToolUse matcher: "Edit|Write"
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""')
+
+# Only check code files
+case "$FILE_PATH" in
+  *.ts|*.tsx|*.js|*.jsx|*.py|*.go|*.rs)
+    ;;
+  *)
+    echo '{"continue": true}'
+    exit 0
+    ;;
+esac
+
+# Get the content that was written
+NEW_CONTENT=""
+if [[ "$TOOL_NAME" == "Write" ]]; then
+  NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // ""')
+elif [[ "$TOOL_NAME" == "Edit" ]]; then
+  NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // ""')
+fi
+
+# Check for debug patterns
+WARNINGS=""
+
+if echo "$NEW_CONTENT" | grep -qE 'console\.(log|debug|info|warn|error)\s*\('; then
+  WARNINGS="⚠️  Debug statement detected: console.log/debug. Remove before commit."
+fi
+
+if echo "$NEW_CONTENT" | grep -qE '^\s*debugger\s*;?\s*$'; then
+  WARNINGS="${WARNINGS}\n⚠️  Debugger statement detected. Remove before commit."
+fi
+
+if echo "$NEW_CONTENT" | grep -qE '^\s*print\s*\('; then
+  WARNINGS="${WARNINGS}\n⚠️  Print statement detected. Remove before commit."
+fi
+
+# Output warning as additional context (non-blocking)
+if [[ -n "$WARNINGS" ]]; then
+  jq -n --arg warn "$WARNINGS" '{
+    "continue": true,
+    "hookSpecificOutput": {
+      "additionalContext": $warn
+    }
+  }'
+else
+  echo '{"continue": true}'
+fi