ralph-cli-sandboxed 0.2.7 → 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/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/once.js

@@ -2,138 +2,9 @@ import { spawn } from "child_process";
 import { existsSync, appendFileSync, mkdirSync } from "fs";
 import { join } from "path";
 import { checkFilesExist, loadConfig, loadPrompt, getPaths, getCliConfig, requireContainer } from "../utils/config.js";
-import { resolvePromptVariables } from "../templates/prompts.js";
-/**
- * Parses a stream-json line and extracts displayable text.
- * Formats output similar to Claude Code's normal terminal display.
- */
-function parseStreamJsonLine(line, debug = false) {
-    try {
-        const json = JSON.parse(line);
-        if (debug && json.type) {
-            process.stderr.write(`[stream-json] type: ${json.type}\n`);
-        }
-        // Handle Claude Code CLI stream-json events
-        const type = json.type;
-        switch (type) {
-            // === Text Content ===
-            case "content_block_delta":
-                // Incremental text updates - the main streaming content
-                if (json.delta?.type === "text_delta") {
-                    return json.delta.text || "";
-                }
-                // Tool input being streamed
-                if (json.delta?.type === "input_json_delta") {
-                    return ""; // Don't show partial JSON, wait for complete tool call
-                }
-                return json.delta?.text || "";
-            case "text":
-                return json.text || "";
-            // === Tool Use ===
-            case "content_block_start":
-                if (json.content_block?.type === "tool_use") {
-                    const toolName = json.content_block?.name || "unknown";
-                    return `\n── Tool: ${toolName} ──\n`;
-                }
-                if (json.content_block?.type === "text") {
-                    return json.content_block?.text || "";
-                }
-                return "";
-            case "content_block_stop":
-                // End of a content block - add newline after tool use
-                return "";
-            // === Tool Results ===
-            case "tool_result":
-                const toolOutput = json.content || json.output || "";
-                const truncated = typeof toolOutput === "string" && toolOutput.length > 500
-                    ? toolOutput.substring(0, 500) + "... (truncated)"
-                    : toolOutput;
-                return `\n── Tool Result ──\n${typeof truncated === "string" ? truncated : JSON.stringify(truncated, null, 2)}\n`;
-            // === Assistant Messages ===
-            case "assistant":
-                const contents = json.message?.content || json.content || [];
-                let output = "";
-                for (const block of contents) {
-                    if (block.type === "text") {
-                        output += block.text || "";
-                    }
-                    else if (block.type === "tool_use") {
-                        output += `\n── Tool: ${block.name} ──\n`;
-                        if (block.input) {
-                            output += JSON.stringify(block.input, null, 2) + "\n";
-                        }
-                    }
-                }
-                return output;
-            case "message_start":
-                // Beginning of a new message
-                return "\n";
-            case "message_delta":
-                // Message completion info (stop_reason, usage)
-                if (json.delta?.stop_reason) {
-                    return `\n[${json.delta.stop_reason}]\n`;
-                }
-                return "";
-            case "message_stop":
-                return "\n";
-            // === System/User Events ===
-            case "system":
-                if (json.message) {
-                    return `[System] ${json.message}\n`;
-                }
-                return "";
-            case "user":
-                // User message echo - usually not needed to display
-                return "";
-            // === Results and Errors ===
-            case "result":
-                if (json.result !== undefined) {
-                    return `\n── Result ──\n${JSON.stringify(json.result, null, 2)}\n`;
-                }
-                return "";
-            case "error":
-                const errMsg = json.error?.message || JSON.stringify(json.error);
-                return `\n[Error] ${errMsg}\n`;
-            // === File Operations (Claude Code specific) ===
-            case "file_edit":
-            case "file_write":
-                const filePath = json.path || json.file || "unknown";
-                return `\n── Writing: ${filePath} ──\n`;
-            case "file_read":
-                const readPath = json.path || json.file || "unknown";
-                return `── Reading: ${readPath} ──\n`;
-            case "bash":
-            case "command":
-                const cmd = json.command || json.content || "";
-                return `\n── Running: ${cmd} ──\n`;
-            case "bash_output":
-            case "command_output":
-                const cmdOutput = json.output || json.content || "";
-                return cmdOutput + "\n";
-            default:
-                // Fallback: check for common text fields
-                if (json.text)
-                    return json.text;
-                if (json.content && typeof json.content === "string")
-                    return json.content;
-                if (json.message && typeof json.message === "string")
-                    return json.message;
-                if (json.output && typeof json.output === "string")
-                    return json.output;
-                if (debug) {
-                    process.stderr.write(`[stream-json] unhandled type: ${type}, keys: ${Object.keys(json).join(", ")}\n`);
-                }
-                return "";
-        }
-    }
-    catch (e) {
-        // Not valid JSON
-        if (debug) {
-            process.stderr.write(`[stream-json] parse error: ${e}\n`);
-        }
-        return "";
-    }
-}
+import { resolvePromptVariables, getCliProviders } from "../templates/prompts.js";
+import { getStreamJsonParser } from "../utils/stream-json.js";
+import { sendNotification } from "../utils/notification.js";
 export async function once(args) {
     // Parse flags
     let debug = false;
@@ -170,6 +41,11 @@ export async function once(args) {
     const streamJsonEnabled = streamJsonConfig?.enabled ?? false;
     const saveRawJson = streamJsonConfig?.saveRawJson !== false; // default true
     const outputDir = config.docker?.asciinema?.outputDir || ".recordings";
+    // Get provider-specific streamJsonArgs (empty array if not defined)
+    // This allows providers without JSON streaming to still have output displayed
+    const providers = getCliProviders();
+    const providerConfig = config.cliProvider ? providers[config.cliProvider] : providers["claude"];
+    const streamJsonArgs = providerConfig?.streamJsonArgs ?? [];
     console.log("Starting single ralph iteration...");
     if (streamJsonEnabled) {
         console.log("Stream JSON output enabled - displaying formatted Claude output");
@@ -182,15 +58,30 @@ export async function once(args) {
     // Use yoloArgs from config if available, otherwise default to Claude's --dangerously-skip-permissions
     const yoloArgs = cliConfig.yoloArgs ?? ["--dangerously-skip-permissions"];
     const promptArgs = cliConfig.promptArgs ?? ["-p"];
-    const promptValue = `@${paths.prd} @${paths.progress} ${prompt}`;
     const cliArgs = [
         ...(cliConfig.args ?? []),
         ...yoloArgs,
     ];
-    // Add stream-json output format if enabled
+    // Build the prompt value based on whether fileArgs is configured
+    // fileArgs (e.g., ["--read"] for Aider) means files are passed as separate arguments
+    // Otherwise, use @file syntax embedded in the prompt (Claude Code style)
+    let promptValue;
+    if (cliConfig.fileArgs && cliConfig.fileArgs.length > 0) {
+        // Add files as separate arguments (e.g., --read prd.json --read progress.txt)
+        for (const fileArg of cliConfig.fileArgs) {
+            cliArgs.push(fileArg, paths.prd);
+            cliArgs.push(fileArg, paths.progress);
+        }
+        promptValue = prompt;
+    }
+    else {
+        // Use @file syntax embedded in the prompt
+        promptValue = `@${paths.prd} @${paths.progress} ${prompt}`;
+    }
+    // Add stream-json output format if enabled (using provider-specific args)
     let jsonLogPath;
     if (streamJsonEnabled) {
-        cliArgs.push("--output-format", "stream-json", "--verbose", "--print");
+        cliArgs.push(...streamJsonArgs);
         // Setup JSON log file if saving raw JSON
         if (saveRawJson) {
             const fullOutputDir = join(process.cwd(), outputDir);
@@ -212,7 +103,12 @@ export async function once(args) {
             console.log(`[debug] Saving raw JSON to: ${jsonLogPath}\n`);
         }
     }
+    // Create provider-specific stream-json parser
+    const streamJsonParser = getStreamJsonParser(config.cliProvider, debug);
+    // Notification options for this run
+    const notifyOptions = { command: config.notifyCommand, debug };
     return new Promise((resolve, reject) => {
+        let output = ""; // Accumulate output for PRD complete detection
         if (streamJsonEnabled) {
             // Stream JSON mode: capture stdout, parse JSON, display clean text
             let lineBuffer = "";
@@ -240,19 +136,21 @@ export async function once(args) {
                                 // Ignore write errors
                             }
                         }
-                        // Parse and display clean text
-                        const text = parseStreamJsonLine(trimmedLine, debug);
+                        // Parse and display clean text using provider-specific parser
+                        const text = streamJsonParser.parseStreamJsonLine(trimmedLine);
                         if (text) {
                             process.stdout.write(text);
+                            output += text; // Accumulate for completion detection
                         }
                     }
                     else {
                         // Non-JSON line - display as-is (might be status messages, errors, etc.)
                         process.stdout.write(trimmedLine + "\n");
+                        output += trimmedLine + "\n";
                     }
                 }
             });
-            proc.on("close", (code) => {
+            proc.on("close", async (code) => {
                 // Process any remaining buffered content
                 if (lineBuffer.trim()) {
                     const trimmedLine = lineBuffer.trim();
@@ -265,20 +163,30 @@ export async function once(args) {
                                 // Ignore write errors
                             }
                         }
-                        const text = parseStreamJsonLine(trimmedLine, debug);
+                        const text = streamJsonParser.parseStreamJsonLine(trimmedLine);
                         if (text) {
                             process.stdout.write(text);
+                            output += text;
                         }
                     }
                     else {
                         // Non-JSON remaining content
                         process.stdout.write(trimmedLine + "\n");
+                        output += trimmedLine + "\n";
                     }
                 }
                 // Ensure final newline
                 process.stdout.write("\n");
+                // Send notification based on outcome
                 if (code !== 0) {
                     console.error(`\n${cliConfig.command} exited with code ${code}`);
+                    await sendNotification("error", `Ralph: Iteration failed with exit code ${code}`, notifyOptions);
+                }
+                else if (output.includes("<promise>COMPLETE</promise>")) {
+                    await sendNotification("prd_complete", undefined, notifyOptions);
+                }
+                else {
+                    await sendNotification("iteration_complete", undefined, notifyOptions);
                 }
                 resolve();
             });
@@ -287,13 +195,26 @@ export async function once(args) {
             });
         }
         else {
-            // Standard mode: pass through all I/O
+            // Standard mode: capture stdout while passing through
             const proc = spawn(cliConfig.command, cliArgs, {
-                stdio: "inherit",
+                stdio: ["inherit", "pipe", "inherit"],
             });
-            proc.on("close", (code) => {
+            proc.stdout.on("data", (data) => {
+                const chunk = data.toString();
+                output += chunk;
+                process.stdout.write(chunk);
+            });
+            proc.on("close", async (code) => {
+                // Send notification based on outcome
                 if (code !== 0) {
                     console.error(`\n${cliConfig.command} exited with code ${code}`);
+                    await sendNotification("error", `Ralph: Iteration failed with exit code ${code}`, notifyOptions);
+                }
+                else if (output.includes("<promise>COMPLETE</promise>")) {
+                    await sendNotification("prd_complete", undefined, notifyOptions);
+                }
+                else {
+                    await sendNotification("iteration_complete", undefined, notifyOptions);
                 }
                 resolve();
             });