ralph-cli-sandboxed 0.2.6 → 0.2.8

package/README.md

@@ -83,6 +83,57 @@ After running `ralph init`, you'll have:
     └── ...
 ```
 
+### Notifications
+
+Ralph can send notifications when events occur during automation. Configure a notification command in `.ralph/config.json`:
+
+```json
+{
+  "notifyCommand": "ntfy pub mytopic"
+}
+```
+
+The message is appended as the last argument to your command. Supported notification tools include:
+
+| Tool | Example Command | Description |
+|------|----------------|-------------|
+| [ntfy](https://ntfy.sh/) | `ntfy pub mytopic` | Push notifications to phone/desktop |
+| notify-send (Linux) | `notify-send Ralph` | Desktop notifications on Linux |
+| terminal-notifier (macOS) | `terminal-notifier -title Ralph -message` | Desktop notifications on macOS |
+| Custom script | `/path/to/notify.sh` | Your own notification script |
+
+#### Notification Events
+
+Ralph sends notifications for these events:
+
+| Event | Message | When |
+|-------|---------|------|
+| PRD Complete | "Ralph: PRD Complete! All tasks finished." | All PRD tasks are marked as passing |
+| Iteration Complete | "Ralph: Iteration complete." | Single `ralph once` iteration finishes |
+| Run Stopped | "Ralph: Run stopped..." | `ralph run` stops due to no progress or max failures |
+| Error | "Ralph: An error occurred." | CLI fails repeatedly |
+
+#### Example: ntfy Setup
+
+[ntfy](https://ntfy.sh/) is a simple HTTP-based pub-sub notification service:
+
+```bash
+# 1. Install ntfy CLI
+pip install ntfy
+
+# 2. Subscribe to your topic on your phone (ntfy app) or browser
+# Visit: https://ntfy.sh/your-unique-topic
+
+# 3. Configure ralph
+# In .ralph/config.json:
+{
+  "notifyCommand": "ntfy pub your-unique-topic"
+}
+
+# 4. Run ralph - you'll get notifications on completion
+ralph docker run
+```
+
 ### Supported Languages
 
 Ralph supports 18 programming languages with pre-configured build/test commands:
@@ -116,8 +167,9 @@ Ralph supports multiple AI CLI tools. Select your provider during `ralph init`:
 |-----|--------|----------------------|-------|
 | [Claude Code](https://github.com/anthropics/claude-code) | Working | `ANTHROPIC_API_KEY` | Default provider. Also supports ~/.claude OAuth credentials |
 | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Working | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | |
-| [OpenCode](https://github.com/anomalyco/opencode) | Working | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY` | Requires [PR #9073](https://github.com/anomalyco/opencode/pull/9073) |
+| [OpenCode](https://github.com/anomalyco/opencode) | Working | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY` | No autonomous/yolo mode yet. Requires [PR #9073](https://github.com/anomalyco/opencode/pull/9073) |
 | [Aider](https://github.com/paul-gauthier/aider) | Working | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` | |
+| [Goose](https://github.com/block/goose) | Working | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` | Block's AI coding agent |
 | [Codex CLI](https://github.com/openai/codex) | Testers wanted | `OPENAI_API_KEY` | Sponsors welcome |
 | [AMP](https://ampcode.com/) | Testers wanted | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | Sponsors welcome |
 | Custom | - | User-defined | Configure your own CLI |
@@ -130,7 +182,7 @@ Ralph can be configured to use different AI CLI tools. By default, it uses Claud
 {
   "cli": {
     "command": "claude",
-    "args": ["--permission-mode", "acceptEdits"],
+    "args": [],
     "modelArgs": ["--model"],
     "promptArgs": ["-p"]
   }
@@ -144,6 +196,102 @@ Ralph can be configured to use different AI CLI tools. By default, it uses Claud
 
 The prompt content and `--dangerously-skip-permissions` (in containers) are added automatically at runtime.
 
+### Stream-JSON Output
+
+Ralph supports stream-json output mode for real-time streaming of AI responses. This feature provides cleaner terminal output and enables recording of raw JSON logs for debugging or replay.
+
+#### Enabling Stream-JSON
+
+Configure stream-json in `.ralph/config.json`:
+
+```json
+{
+  "docker": {
+    "asciinema": {
+      "enabled": true,
+      "autoRecord": true,
+      "outputDir": ".recordings",
+      "streamJson": {
+        "enabled": true,
+        "saveRawJson": true
+      }
+    }
+  }
+}
+```
+
+Configuration options:
+- `enabled`: Enable stream-json output mode (default: `false`)
+- `saveRawJson`: Save raw JSON output to `.jsonl` files (default: `true` when enabled)
+- `outputDir`: Directory for recordings and logs (default: `.recordings`)
+
+#### Provider Compatibility
+
+Not all CLI providers support stream-json output. Here's the compatibility matrix:
+
+| CLI Provider | Stream-JSON Support | Arguments Used |
+|--------------|---------------------|----------------|
+| Claude Code | ✅ Yes | `--output-format stream-json --verbose --print` |
+| Gemini CLI | ✅ Yes | `--output-format json` |
+| OpenCode | ✅ Yes | `--format json` |
+| Codex CLI | ✅ Yes | `--json` |
+| Goose | ✅ Yes | `--output-format stream-json` |
+| Aider | ❌ No | - |
+| AMP | ❌ No | - |
+| Custom | ❌ No* | *Add `streamJsonArgs` to your custom config |
+
+Each provider uses different command-line arguments and output formats. Ralph automatically selects the correct parser based on your configured provider.
+
+#### Output Files
+
+When stream-json is enabled, Ralph creates the following files in the `.recordings/` directory (configurable via `outputDir`):
+
+| File Type | Pattern | Description |
+|-----------|---------|-------------|
+| `.jsonl` | `ralph-run-YYYYMMDD-HHMMSS.jsonl` | Raw JSON Lines log from `ralph run` |
+| `.jsonl` | `ralph-once-YYYYMMDD-HHMMSS.jsonl` | Raw JSON Lines log from `ralph once` |
+| `.cast` | `session-YYYYMMDD-HHMMSS.cast` | Asciinema terminal recording (when asciinema enabled) |
+
+The `.jsonl` files contain one JSON object per line with the raw streaming events from the AI provider. These files are useful for:
+- Debugging AI responses
+- Replaying sessions
+- Analyzing tool calls and outputs
+- Building custom post-processing pipelines
+
+#### Troubleshooting Stream-JSON
+
+**Stream-JSON not working:**
+1. Verify your CLI provider supports stream-json (see compatibility matrix above)
+2. Check that `streamJson.enabled` is set to `true` in config
+3. Ensure your CLI provider is correctly installed and accessible
+
+**No output appearing:**
+- Stream-json parsing extracts human-readable text from JSON events
+- Some providers emit different event types; Ralph handles the most common ones
+- Use `--debug` flag with ralph commands to see raw parsing output: `[stream-json]` prefixed lines go to stderr
+
+**Missing .jsonl files:**
+- Verify `saveRawJson` is `true` (or not set, as it defaults to `true`)
+- Check that the `outputDir` directory is writable
+- Files are created at command start; check for permission errors
+
+**Parser not recognizing events:**
+- Each provider has a specific parser (ClaudeStreamParser, GeminiStreamParser, etc.)
+- Unknown event types are handled by a default parser that extracts common fields
+- If you see raw JSON in output, the parser may not support that event type yet
+
+**Custom CLI provider:**
+To add stream-json support for a custom CLI provider, add `streamJsonArgs` to your CLI config:
+```json
+{
+  "cli": {
+    "command": "my-cli",
+    "promptArgs": ["-p"],
+    "streamJsonArgs": ["--json-output"]
+  }
+}
+```
+
 ## PRD Format
 
 The PRD (`prd.json`) is an array of requirements:
@@ -181,11 +329,45 @@ File paths are resolved relative to the project root. Absolute paths are also su
 
 Ralph includes automatic PRD protection to handle cases where the LLM corrupts the PRD structure:
 
-- **Automatic backup**: Before each run, the PRD is backed up
+- **Automatic backup**: Before each run, the PRD is backed up to `.ralph/backups/`
 - **Validation**: After each iteration, the PRD structure is validated
 - **Smart recovery**: If corrupted, ralph attempts to extract `passes: true` flags from the corrupted PRD and merge them into the backup
 - **Manual recovery**: Use `ralph fix-prd` to validate, auto-fix, or restore from a specific backup
 
+### When PRD Corruption Happens
+
+LLMs sometimes modify the PRD file incorrectly, such as:
+- Converting the array to an object
+- Adding invalid JSON syntax
+- Changing the structure entirely
+
+If you see an error like:
+```
+Error: prd.json is corrupted - expected an array of items.
+The file may have been modified incorrectly by an LLM.
+
+Run ralph fix-prd to diagnose and repair the file.
+```
+
+### Using fix-prd
+
+The `ralph fix-prd` command diagnoses and repairs corrupted PRD files:
+
+```bash
+ralph fix-prd              # Auto-diagnose and fix
+ralph fix-prd --verify     # Check structure without modifying
+ralph fix-prd backup.json  # Restore from a specific backup file
+```
+
+**What fix-prd does:**
+1. Validates JSON syntax and structure
+2. Checks that all required fields exist (category, description, steps, passes)
+3. Attempts to recover `passes: true` flags from corrupted files
+4. Falls back to the most recent backup if recovery fails
+5. Creates a fresh template PRD as a last resort
+
+**Backups are stored in:** `.ralph/backups/backup.prd.YYYY-MM-DD-HHMMSS.json`
+
 ### Dynamic Iteration Limits
 
 To prevent runaway loops, `ralph run` limits iterations to `incomplete_tasks + 3`. This limit adjusts dynamically if new tasks are added during execution.

package/dist/commands/docker.js

@@ -113,6 +113,7 @@ RUN ${gitCommands.join(' \\\n    && ')}
     // Build asciinema installation section if enabled
     let asciinemaInstall = '';
     let asciinemaDir = '';
+    let streamScriptCopy = '';
     if (dockerConfig?.asciinema?.enabled) {
         const outputDir = dockerConfig.asciinema.outputDir || '.recordings';
         asciinemaInstall = `
@@ -123,6 +124,14 @@ RUN apt-get update && apt-get install -y asciinema && rm -rf /var/lib/apt/lists/
 # Create asciinema recordings directory
 RUN mkdir -p /workspace/${outputDir} && chown node:node /workspace/${outputDir}
 `;
+        // Add stream script if streamJson is enabled
+        if (dockerConfig.asciinema.streamJson?.enabled) {
+            streamScriptCopy = `
+# Copy ralph stream wrapper script for clean JSON output
+COPY ralph-stream.sh /usr/local/bin/ralph-stream.sh
+RUN chmod +x /usr/local/bin/ralph-stream.sh
+`;
+        }
     }
     return `# Ralph CLI Sandbox Environment
 # Based on Claude Code devcontainer
@@ -218,7 +227,7 @@ ENV EDITOR=nano
 # Add bash aliases and prompt (fallback if using bash)
 RUN echo 'alias ll="ls -la"' >> /etc/bash.bashrc && \\
     echo 'PS1="\\[\\033[43;30m\\][ralph]\\w\\[\\033[0m\\]\\$ "' >> /etc/bash.bashrc
-${rootBuildCommands}${asciinemaInstall}
+${rootBuildCommands}${asciinemaInstall}${streamScriptCopy}
 # Switch to non-root user
 USER node
 ${gitConfigSection}${nodeBuildCommands}
@@ -364,11 +373,21 @@ function generateDockerCompose(imageName, dockerConfig) {
     }
     // Build command section if configured
     let commandSection = '';
+    let streamJsonNote = '';
     if (dockerConfig?.asciinema?.enabled && dockerConfig?.asciinema?.autoRecord) {
         // Wrap with asciinema recording
         const outputDir = dockerConfig.asciinema.outputDir || '.recordings';
         const innerCommand = dockerConfig.startCommand || 'zsh';
         commandSection = `    command: bash -c "mkdir -p /workspace/${outputDir} && asciinema rec -c '${innerCommand}' /workspace/${outputDir}/session-$$(date +%Y%m%d-%H%M%S).cast"\n`;
+        // Add note about stream-json if enabled
+        if (dockerConfig.asciinema.streamJson?.enabled) {
+            streamJsonNote = `
+    # Stream JSON mode enabled - use ralph-stream.sh for clean Claude output:
+    #   ralph-stream.sh -p "your prompt here"
+    # This formats stream-json output for readable terminal display.
+    # Raw JSON is saved to ${outputDir}/session-*.jsonl for later analysis.
+`;
+        }
     }
     else if (dockerConfig?.startCommand) {
         commandSection = `    command: ${dockerConfig.startCommand}\n`;
@@ -394,7 +413,7 @@ ${environmentSection}    working_dir: /workspace
     tty: true
     cap_add:
       - NET_ADMIN  # Required for firewall
-${commandSection}
+${streamJsonNote}${commandSection}
 volumes:
   ${imageName}-history:
 `;
@@ -405,6 +424,82 @@ dist
 .git
 *.log
 `;
+// Generate stream wrapper script for clean asciinema recordings
+function generateStreamScript(outputDir, saveRawJson) {
+    const saveJsonSection = saveRawJson ? `
+# Save raw JSON for later analysis
+JSON_LOG="$OUTPUT_DIR/session-$TIMESTAMP.jsonl"
+TEE_CMD="tee \\"$JSON_LOG\\""` : `
+TEE_CMD="cat"`;
+    return `#!/bin/bash
+# Ralph stream wrapper - formats Claude stream-json output for clean terminal display
+# Generated by ralph-cli
+
+set -e
+
+OUTPUT_DIR="\${RALPH_RECORDING_DIR:-/workspace/${outputDir}}"
+TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+
+# Ensure output directory exists
+mkdir -p "$OUTPUT_DIR"
+${saveJsonSection}
+
+# jq filter to extract and format content from stream-json
+# Handles text, tool calls, tool results, file operations, and commands
+JQ_FILTER='
+  if .type == "content_block_delta" then
+    (if .delta.type == "text_delta" then .delta.text // empty
+     elif .delta.text then .delta.text
+     else empty end)
+  elif .type == "content_block_start" then
+    (if .content_block.type == "tool_use" then "\\n── Tool: " + (.content_block.name // "unknown") + " ──\\n"
+     elif .content_block.type == "text" then .content_block.text // empty
+     else empty end)
+  elif .type == "tool_result" then
+    "\\n── Tool Result ──\\n" + ((.content // .output // "") | tostring) + "\\n"
+  elif .type == "assistant" then
+    ([.message.content[]? | select(.type == "text") | .text] | join(""))
+  elif .type == "message_start" then
+    "\\n"
+  elif .type == "message_delta" then
+    (if .delta.stop_reason then "\\n[" + .delta.stop_reason + "]\\n" else empty end)
+  elif .type == "file_edit" or .type == "file_write" then
+    "\\n── Writing: " + (.path // .file // "unknown") + " ──\\n"
+  elif .type == "file_read" then
+    "── Reading: " + (.path // .file // "unknown") + " ──\\n"
+  elif .type == "bash" or .type == "command" then
+    "\\n── Running: " + (.command // .content // "") + " ──\\n"
+  elif .type == "bash_output" or .type == "command_output" then
+    (.output // .content // "") + "\\n"
+  elif .type == "result" then
+    (if .result then "\\n── Result ──\\n" + (.result | tostring) + "\\n" else empty end)
+  elif .type == "error" then
+    "\\n[Error] " + (.error.message // (.error | tostring)) + "\\n"
+  elif .type == "system" then
+    (if .message then "[System] " + .message + "\\n" else empty end)
+  elif .text then
+    .text
+  elif (.content | type) == "string" then
+    .content
+  else
+    empty
+  end
+'
+
+# Pass all arguments to claude with stream-json output
+# Filter JSON lines, optionally save raw JSON, and display formatted text
+claude \\
+  --output-format stream-json \\
+  --verbose \\
+  --print \\
+  "\$@" 2>&1 \\
+| grep --line-buffered '^{' \\
+| eval $TEE_CMD \\
+| jq --unbuffered -rj "$JQ_FILTER"
+
+echo ""  # Ensure final newline
+`;
+}
 // Generate .mcp.json content for Claude Code MCP servers
 function generateMcpJson(mcpServers) {
     return JSON.stringify({ mcpServers }, null, 2);
@@ -432,6 +527,12 @@ async function generateFiles(ralphDir, language, imageName, force = false, javaV
         { name: "docker-compose.yml", content: generateDockerCompose(imageName, dockerConfig) },
         { name: ".dockerignore", content: DOCKERIGNORE },
     ];
+    // Add stream script if streamJson is enabled
+    if (dockerConfig?.asciinema?.enabled && dockerConfig.asciinema.streamJson?.enabled) {
+        const outputDir = dockerConfig.asciinema.outputDir || '.recordings';
+        const saveRawJson = dockerConfig.asciinema.streamJson.saveRawJson !== false; // default true
+        files.push({ name: "ralph-stream.sh", content: generateStreamScript(outputDir, saveRawJson) });
+    }
     for (const file of files) {
         const filePath = join(dockerDir, file.name);
         if (existsSync(filePath) && !force) {

package/dist/commands/help.js

@@ -93,7 +93,7 @@ CLI CONFIGURATION:
   {
     "cli": {
       "command": "claude",
-      "args": ["--permission-mode", "acceptEdits"],
+      "args": [],
       "yoloArgs": ["--dangerously-skip-permissions"]
     },
     "cliProvider": "claude"
@@ -104,6 +104,7 @@ CLI CONFIGURATION:
     - aider: AI pair programming
     - codex: OpenAI Codex CLI
     - gemini: Google Gemini CLI
+    - goose: Block's Goose AI coding agent
     - opencode: Open source AI coding agent
     - amp: Sourcegraph AMP CLI
     - custom: Configure your own CLI

package/dist/commands/init.js

@@ -1,7 +1,7 @@
 import { existsSync, writeFileSync, mkdirSync, copyFileSync } from "fs";
 import { join, basename, dirname } from "path";
 import { fileURLToPath } from "url";
-import { getLanguages, generatePromptTemplate, DEFAULT_PRD, DEFAULT_PROGRESS, getCliProviders } from "../templates/prompts.js";
+import { getLanguages, generatePromptTemplate, DEFAULT_PRD, DEFAULT_PROGRESS, getCliProviders, getSkillsForLanguage } from "../templates/prompts.js";
 import { promptSelectWithArrows, promptConfirm, promptInput, promptMultiSelectWithArrows } from "../utils/prompt.js";
 import { dockerInit } from "./docker.js";
 // Get package root directory (works for both dev and installed package)
@@ -39,6 +39,7 @@ export async function init(args) {
     let cliConfig;
     let selectedKey;
     let selectedTechnologies = [];
+    let selectedSkills = [];
     let checkCommand;
     let testCommand;
     if (useDefaults) {
@@ -115,6 +116,29 @@ export async function init(args) {
                 console.log("\nNo technologies selected.");
             }
         }
+        // Step 4: Select skills if available for this language
+        const availableSkills = getSkillsForLanguage(selectedKey);
+        if (availableSkills.length > 0) {
+            const skillOptions = availableSkills.map(s => `${s.name} - ${s.description}`);
+            const selectedSkillNames = await promptMultiSelectWithArrows("Select AI coding rules/skills to enable (optional):", skillOptions);
+            // Convert selected display names to SkillConfig objects
+            selectedSkills = selectedSkillNames.map(sel => {
+                const idx = skillOptions.indexOf(sel);
+                const skill = availableSkills[idx];
+                return {
+                    name: skill.name,
+                    description: skill.description,
+                    instructions: skill.instructions,
+                    userInvocable: skill.userInvocable,
+                };
+            });
+            if (selectedSkills.length > 0) {
+                console.log(`\nSelected skills: ${selectedSkills.map(s => s.name).join(", ")}`);
+            }
+            else {
+                console.log("\nNo skills selected.");
+            }
+        }
         // Allow custom commands for "none" language
         checkCommand = config.checkCommand;
         testCommand = config.testCommand;
@@ -164,6 +188,10 @@ export async function init(args) {
                 enabled: false,
                 autoRecord: false,
                 outputDir: ".recordings",
+                streamJson: {
+                    enabled: false,
+                    saveRawJson: true,
+                },
             },
             firewall: {
                 allowedDomains: [],
@@ -172,7 +200,7 @@ export async function init(args) {
         // Claude-specific configuration (MCP servers and skills)
         claude: {
             mcpServers: {},
-            skills: [],
+            skills: selectedSkills,
         },
     };
     const configPath = join(ralphDir, CONFIG_FILE);