refactor: replace exportName with name throughout codebase

- Update TpmjsToolDefinitionSchema to only use 'name' field
- Add 'sandbox' as valid category for sprites tools
- Update all package.json files to use 'name' instead of 'exportName'
- Update documentation and source files accordingly
- Add 11 new sprites tools for sandbox/code-execution
This commit is contained in:
Ajax Davis 2026-01-14 14:18:36 +10:00
parent b1dd3371cd
commit 2cd2b10cd0
91 changed files with 4019 additions and 195 deletions

View file

@ -0,0 +1,16 @@
---
description: Cancel the active Ralph loop
command: rm -f .claude/ralph-loop.local.md && echo "Ralph loop cancelled"
---
# Cancel Ralph Loop
Immediately cancel any active Ralph loop and allow normal session exit.
## Usage
```
/cancel-ralph
```
This removes the state file that drives the loop, allowing the session to exit normally.

View file

@ -0,0 +1,43 @@
---
description: Start Ralph Wiggum loop in current session
command: "${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
---
# Ralph Loop
Start an iterative development loop that continues until the task is complete.
## Usage
```
/ralph-loop "Your task description" [--max-iterations N] [--validation-script PATH] [--completion-promise TEXT]
```
## How It Works
1. You provide a task and optional validation criteria
2. Claude works on the task
3. When Claude tries to exit, the stop hook intercepts
4. If validation fails OR completion promise not met, the loop continues
5. Claude sees previous work and continues iterating
6. Loop ends when validation passes or max iterations reached
## Important Rules
- If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE
- Do NOT use false completion promises as an exit strategy
- The loop persists until genuine completion is achieved
- Use validation scripts for programmatic verification
## Examples
```bash
# With validation script only
/ralph-loop "Build the SDK package" --validation-script ./scripts/validate-sdk.sh
# With completion promise
/ralph-loop "Fix all type errors" --completion-promise "ALL_TYPES_PASS"
# With both
/ralph-loop "Complete feature X" --max-iterations 15 --validation-script ./validate.sh --completion-promise "FEATURE_COMPLETE"
```

View file

@ -0,0 +1,15 @@
{
"description": "Ralph Wiggum plugin stop hook for self-referential loops",
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/stop-hook.sh"
}
]
}
]
}
}

View file

@ -0,0 +1,111 @@
#!/bin/bash
# Ralph Wiggum Stop Hook - Self-referential loop for iterative development
# This hook intercepts the Stop event and decides whether to continue the loop
set -euo pipefail
STATE_FILE=".claude/ralph-loop.local.md"
TRANSCRIPT_FILE="${CLAUDE_TRANSCRIPT:-}"
# Check if ralph loop is active
if [[ ! -f "$STATE_FILE" ]]; then
# No active loop, allow normal exit
exit 0
fi
# Parse the state file frontmatter
parse_frontmatter() {
local key="$1"
sed -n '/^---$/,/^---$/p' "$STATE_FILE" | grep "^${key}:" | sed "s/^${key}: *//" | tr -d '"'
}
iteration=$(parse_frontmatter "iteration")
max_iterations=$(parse_frontmatter "max_iterations")
completion_promise=$(parse_frontmatter "completion_promise")
prompt=$(parse_frontmatter "prompt")
validation_script=$(parse_frontmatter "validation_script")
# Validate numeric fields
if ! [[ "$iteration" =~ ^[0-9]+$ ]]; then
echo "Error: Invalid iteration count in state file" >&2
rm -f "$STATE_FILE"
exit 0
fi
if ! [[ "$max_iterations" =~ ^[0-9]+$ ]]; then
echo "Error: Invalid max_iterations in state file" >&2
rm -f "$STATE_FILE"
exit 0
fi
# Check if max iterations reached
if [[ "$max_iterations" -gt 0 ]] && [[ "$iteration" -ge "$max_iterations" ]]; then
echo "Ralph loop reached max iterations ($max_iterations). Exiting." >&2
rm -f "$STATE_FILE"
exit 0
fi
# Run validation script if provided
validation_passed=false
if [[ -n "$validation_script" ]] && [[ -f "$validation_script" ]]; then
echo "Running validation script: $validation_script" >&2
if bash "$validation_script" 2>&1; then
validation_passed=true
echo "Validation PASSED!" >&2
else
echo "Validation FAILED. Continuing loop..." >&2
fi
fi
# Check for completion promise in transcript
if [[ -n "$completion_promise" ]] && [[ -n "$TRANSCRIPT_FILE" ]] && [[ -f "$TRANSCRIPT_FILE" ]]; then
# Get the last assistant message
last_message=$(tail -100 "$TRANSCRIPT_FILE" | grep -o '<promise>[^<]*</promise>' | tail -1 | sed 's/<promise>\(.*\)<\/promise>/\1/' || true)
if [[ "$last_message" == "$completion_promise" ]]; then
# Also check if validation passed (if validation script exists)
if [[ -z "$validation_script" ]] || [[ "$validation_passed" == "true" ]]; then
echo "Completion promise matched and validation passed. Ralph loop complete!" >&2
rm -f "$STATE_FILE"
exit 0
else
echo "Completion promise matched but validation failed. Continuing..." >&2
fi
fi
fi
# If validation passed without explicit promise, we can exit
if [[ "$validation_passed" == "true" ]] && [[ -z "$completion_promise" ]]; then
echo "Validation passed. Ralph loop complete!" >&2
rm -f "$STATE_FILE"
exit 0
fi
# Increment iteration
new_iteration=$((iteration + 1))
# Update state file
sed -i.bak "s/^iteration: .*/iteration: $new_iteration/" "$STATE_FILE"
rm -f "${STATE_FILE}.bak"
# Build the continuation message
cat << EOF
{
"decision": "block",
"reason": "Ralph loop iteration $new_iteration of $max_iterations",
"message": "
---
RALPH LOOP - Iteration $new_iteration / $max_iterations
---
Continue working on the task. Your previous iteration's work is preserved in the codebase.
TASK: $prompt
$(if [[ -n "$validation_script" ]]; then echo "VALIDATION: Run the validation to check progress. Script: $validation_script"; fi)
$(if [[ -n "$completion_promise" ]]; then echo "COMPLETION: Output <promise>$completion_promise</promise> ONLY when the task is completely done AND validation passes."; fi)
Review what you've done so far and continue from where you left off.
"
}
EOF

View file

@ -0,0 +1,120 @@
#!/bin/bash
# Setup Ralph Loop - Initialize the iterative development loop
# Usage: setup-ralph-loop.sh "PROMPT" [--max-iterations N] [--completion-promise TEXT] [--validation-script PATH]
set -euo pipefail
STATE_FILE=".claude/ralph-loop.local.md"
# Default values
MAX_ITERATIONS=20
COMPLETION_PROMISE=""
VALIDATION_SCRIPT=""
PROMPT=""
# Parse arguments
while [[ $# -gt 0 ]]; do
case $1 in
--max-iterations)
MAX_ITERATIONS="$2"
shift 2
;;
--completion-promise)
COMPLETION_PROMISE="$2"
shift 2
;;
--validation-script)
VALIDATION_SCRIPT="$2"
shift 2
;;
--help|-h)
cat << EOF
Ralph Loop Setup
Usage: setup-ralph-loop.sh "PROMPT" [OPTIONS]
Options:
--max-iterations N Maximum iterations before stopping (default: 20, 0 = unlimited)
--completion-promise TXT Phrase to output when complete (use <promise>TXT</promise>)
--validation-script PATH Script to run for validation (exit 0 = pass)
--help, -h Show this help
Example:
setup-ralph-loop.sh "Build the SDK package" --max-iterations 10 --validation-script ./validate.sh
EOF
exit 0
;;
*)
if [[ -z "$PROMPT" ]]; then
PROMPT="$1"
else
PROMPT="$PROMPT $1"
fi
shift
;;
esac
done
# Validate prompt
if [[ -z "$PROMPT" ]]; then
echo "Error: PROMPT is required" >&2
exit 1
fi
# Validate max iterations
if ! [[ "$MAX_ITERATIONS" =~ ^[0-9]+$ ]]; then
echo "Error: --max-iterations must be a number" >&2
exit 1
fi
# Validate validation script exists if provided
if [[ -n "$VALIDATION_SCRIPT" ]] && [[ ! -f "$VALIDATION_SCRIPT" ]]; then
echo "Error: Validation script not found: $VALIDATION_SCRIPT" >&2
exit 1
fi
# Create state directory
mkdir -p "$(dirname "$STATE_FILE")"
# Create state file
cat << EOF > "$STATE_FILE"
---
iteration: 1
max_iterations: $MAX_ITERATIONS
completion_promise: "$COMPLETION_PROMISE"
validation_script: "$VALIDATION_SCRIPT"
prompt: "$PROMPT"
started_at: "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
---
# Ralph Loop State
This file tracks the state of an active Ralph loop. DO NOT DELETE while loop is running.
## Configuration
- **Task**: $PROMPT
- **Max Iterations**: $MAX_ITERATIONS
- **Validation Script**: ${VALIDATION_SCRIPT:-"None"}
- **Completion Promise**: ${COMPLETION_PROMISE:-"None (validation only)"}
## Progress Log
Iteration logs will be appended below as the loop progresses.
---
EOF
echo "Ralph loop initialized!"
echo " Task: $PROMPT"
echo " Max iterations: $MAX_ITERATIONS"
echo " Validation: ${VALIDATION_SCRIPT:-"None"}"
echo " Completion promise: ${COMPLETION_PROMISE:-"None"}"
echo ""
echo "The loop will continue until:"
if [[ -n "$VALIDATION_SCRIPT" ]]; then
echo " - Validation script passes ($VALIDATION_SCRIPT returns exit code 0)"
fi
if [[ -n "$COMPLETION_PROMISE" ]]; then
echo " - You output: <promise>$COMPLETION_PROMISE</promise>"
fi
echo " - OR max iterations ($MAX_ITERATIONS) is reached"