ralph-cli-sandboxed 0.2.9 → 0.4.0

package/README.md

@@ -45,6 +45,8 @@ ralph docker run
 | `ralph fix-prd [opts]` | Validate and recover corrupted PRD file |
 | `ralph prompt [opts]` | Display resolved prompt |
 | `ralph docker <sub>` | Manage Docker sandbox environment |
+| `ralph daemon <sub>` | Manage host daemon for sandbox notifications |
+| `ralph notify [msg]` | Send notification (from sandbox to host) |
 | `ralph help` | Show help message |
 
 > **Note:** `ralph prd <subcommand>` still works for compatibility (e.g., `ralph prd add`).
@@ -85,19 +87,51 @@ 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`:
+Ralph can send notifications when events occur during automation. Configure notifications in `.ralph/config.json`:
+
+#### Using ntfy (Recommended)
+
+[ntfy](https://ntfy.sh/) is a simple HTTP-based pub-sub notification service. Ralph uses curl to send notifications, so **no ntfy CLI installation is required**:
+
+```json
+{
+  "notifications": {
+    "provider": "ntfy",
+    "ntfy": {
+      "topic": "my-ralph-notifications",
+      "server": "https://ntfy.sh"
+    }
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `provider` | Set to `"ntfy"` for ntfy notifications |
+| `ntfy.topic` | Your unique topic name (required) |
+| `ntfy.server` | ntfy server URL (default: `https://ntfy.sh`) |
+
+To receive notifications:
+1. Subscribe to your topic on your phone ([ntfy app](https://ntfy.sh/)) or browser (`https://ntfy.sh/your-topic`)
+2. Run `ralph docker run` - you'll get notifications on completion
+
+#### Using a Custom Command
+
+For other notification tools, use the `command` provider:
 
 ```json
 {
-  "notifyCommand": "ntfy pub mytopic"
+  "notifications": {
+    "provider": "command",
+    "command": "notify-send Ralph"
+  }
 }
 ```
 
-The message is appended as the last argument to your command. Supported notification tools include:
+The message is appended as the last argument to your command. Supported 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 |
@@ -113,25 +147,75 @@ Ralph sends notifications for these events:
 | 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
+#### Sandbox-to-Host Notifications (Daemon)
 
-[ntfy](https://ntfy.sh/) is a simple HTTP-based pub-sub notification service:
+When running in a Docker sandbox, notifications are sent via the ralph daemon which runs on the host. The sandbox communicates with the daemon through a shared message file (`.ralph/messages.json`).
 
 ```bash
-# 1. Install ntfy CLI
-pip install ntfy
+# Terminal 1: Start daemon on host
+ralph daemon start
 
-# 2. Subscribe to your topic on your phone (ntfy app) or browser
-# Visit: https://ntfy.sh/your-unique-topic
+# Terminal 2: Run container
+ralph docker run
+
+# Inside container: Send notification manually
+ralph notify "Hello from sandbox!"
+```
+
+The daemon watches for messages and executes the configured notification command on the host. This file-based approach works on all platforms (macOS, Linux, Windows) and allows other tools to integrate with the message queue.
 
-# 3. Configure ralph
-# In .ralph/config.json:
+#### Custom Daemon Actions
+
+You can define custom actions that the sandbox can trigger. This example logs task completions and ralph finished events to a file:
+
+```json
 {
-  "notifyCommand": "ntfy pub your-unique-topic"
+  "daemon": {
+    "actions": {
+      "log_task": {
+        "command": "echo \"$(date '+%Y-%m-%d %H:%M:%S') - Task completed:\" >> log.txt && echo",
+        "description": "Log task completion to file"
+      },
+      "log_complete": {
+        "command": "echo \"$(date '+%Y-%m-%d %H:%M:%S') - Ralph finished: All PRD tasks complete\" >> log.txt",
+        "description": "Log ralph completion to file"
+      }
+    },
+    "events": {
+      "task_complete": [
+        {
+          "action": "log_task",
+          "message": "{{task}}"
+        }
+      ],
+      "ralph_complete": [
+        {
+          "action": "log_complete"
+        },
+        {
+          "action": "notify",
+          "message": "All tasks done!"
+        }
+      ]
+    }
+  }
 }
+```
 
-# 4. Run ralph - you'll get notifications on completion
-ralph docker run
+| Event | When Triggered |
+|-------|----------------|
+| `task_complete` | After each PRD task is marked as passing |
+| `ralph_complete` | When all PRD tasks are complete |
+| `iteration_complete` | After each `ralph once` iteration |
+| `error` | When an error occurs |
+
+The `{{task}}` placeholder is replaced with the task description. Events can trigger multiple actions - for example, `ralph_complete` above both logs to file and sends a notification.
+
+Example `log.txt` output:
+```
+2024-01-15 14:23:01 - Task completed: Add user authentication
+2024-01-15 14:45:32 - Task completed: Implement JWT tokens
+2024-01-15 15:02:18 - Ralph finished: All PRD tasks complete
 ```
 
 ### Supported Languages

package/dist/commands/action.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Execute an action from config.json - works both inside and outside containers.
+ *
+ * Inside container: Uses file-based message queue to communicate with host daemon
+ * Outside container: Executes the command directly
+ */
+export declare function action(args: string[]): Promise<void>;

package/dist/commands/action.js

@@ -0,0 +1,276 @@
+import { spawn } from "child_process";
+import { existsSync } from "fs";
+import { loadConfig, isRunningInContainer } from "../utils/config.js";
+import { getMessagesPath, sendMessage, waitForResponse, } from "../utils/message-queue.js";
+/**
+ * Execute an action from config.json - works both inside and outside containers.
+ *
+ * Inside container: Uses file-based message queue to communicate with host daemon
+ * Outside container: Executes the command directly
+ */
+export async function action(args) {
+    // Parse arguments
+    let actionName;
+    let actionArgs = [];
+    let debug = false;
+    let showList = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--debug" || arg === "-d") {
+            debug = true;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            showHelp();
+            return;
+        }
+        else if (arg === "--list" || arg === "-l") {
+            showList = true;
+        }
+        else if (!arg.startsWith("-")) {
+            if (!actionName) {
+                actionName = arg;
+            }
+            else {
+                // Collect remaining args as action arguments
+                actionArgs = args.slice(i);
+                break;
+            }
+        }
+    }
+    // Load config
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch {
+        console.error("Failed to load config. Run 'ralph init' first.");
+        process.exit(1);
+    }
+    // Get available actions from daemon config
+    const daemonActions = config.daemon?.actions || {};
+    const actionNames = Object.keys(daemonActions);
+    // If --list or no action specified, show available actions
+    if (showList || !actionName) {
+        if (actionNames.length === 0) {
+            console.log("No actions configured.");
+            console.log("");
+            console.log("Configure actions in .ralph/config.json:");
+            console.log('  {');
+            console.log('    "daemon": {');
+            console.log('      "actions": {');
+            console.log('        "build": {');
+            console.log('          "command": "./scripts/build.sh",');
+            console.log('          "description": "Build the project"');
+            console.log('        }');
+            console.log('      }');
+            console.log('    }');
+            console.log('  }');
+        }
+        else {
+            console.log("Available actions:");
+            console.log("");
+            for (const [name, actionConfig] of Object.entries(daemonActions)) {
+                const desc = actionConfig.description || actionConfig.command;
+                console.log(`  ${name.padEnd(20)} ${desc}`);
+            }
+            console.log("");
+            console.log("Run an action: ralph action <name> [args...]");
+        }
+        return;
+    }
+    // Validate action exists
+    if (!daemonActions[actionName]) {
+        console.error(`Unknown action: ${actionName}`);
+        console.error("");
+        if (actionNames.length > 0) {
+            console.error(`Available actions: ${actionNames.join(", ")}`);
+        }
+        else {
+            console.error("No actions configured in .ralph/config.json");
+        }
+        process.exit(1);
+    }
+    const actionConfig = daemonActions[actionName];
+    const inContainer = isRunningInContainer();
+    if (debug) {
+        console.log(`[action] Name: ${actionName}`);
+        console.log(`[action] Args: ${actionArgs.join(" ") || "(none)"}`);
+        console.log(`[action] Command: ${actionConfig.command}`);
+        console.log(`[action] In container: ${inContainer}`);
+    }
+    if (inContainer) {
+        // Inside container - use file-based message queue to execute on host
+        await executeViaQueue(actionName, actionArgs, debug);
+    }
+    else {
+        // Outside container - execute directly
+        await executeDirectly(actionConfig.command, actionArgs, debug);
+    }
+}
+/**
+ * Execute action via message queue (when running inside container).
+ */
+async function executeViaQueue(actionName, args, debug) {
+    const messagesPath = getMessagesPath(true);
+    if (!existsSync(messagesPath)) {
+        const ralphDir = "/workspace/.ralph";
+        if (!existsSync(ralphDir)) {
+            console.error("Error: .ralph directory not mounted in container.");
+            console.error("Make sure the container is started with 'ralph docker run'.");
+            process.exit(1);
+        }
+    }
+    // Send message via file queue
+    const messageId = sendMessage(messagesPath, "sandbox", actionName, args.length > 0 ? args : undefined);
+    if (debug) {
+        console.log(`[action] Sent message: ${messageId}`);
+    }
+    console.log(`Executing action: ${actionName}`);
+    console.log("Waiting for daemon response...");
+    // Wait for response with longer timeout for actions that may take time
+    const response = await waitForResponse(messagesPath, messageId, 60000);
+    if (!response) {
+        console.error("No response from daemon (timeout).");
+        console.error("");
+        console.error("Make sure the daemon is running on the host:");
+        console.error("  ralph daemon start");
+        process.exit(1);
+    }
+    if (debug) {
+        console.log(`[action] Response: ${JSON.stringify(response)}`);
+    }
+    // Display output
+    if (response.output) {
+        console.log("");
+        console.log(response.output);
+    }
+    if (response.success) {
+        console.log("");
+        console.log(`Action '${actionName}' completed successfully.`);
+    }
+    else {
+        console.error("");
+        console.error(`Action '${actionName}' failed: ${response.error || "Unknown error"}`);
+        process.exit(1);
+    }
+}
+/**
+ * Execute action directly on host (when running outside container).
+ */
+async function executeDirectly(command, args, debug) {
+    return new Promise((resolve, reject) => {
+        // Build full command with arguments
+        let fullCommand = command;
+        if (args.length > 0) {
+            fullCommand = `${command} ${args.map(a => `"${a.replace(/"/g, '\\"')}"`).join(" ")}`;
+        }
+        if (debug) {
+            console.log(`[action] Executing: ${fullCommand}`);
+        }
+        console.log(`Executing: ${fullCommand}`);
+        console.log("");
+        const proc = spawn(fullCommand, [], {
+            stdio: ["inherit", "pipe", "pipe"],
+            shell: true,
+            cwd: process.cwd(),
+        });
+        // Stream stdout in real-time
+        proc.stdout.on("data", (data) => {
+            process.stdout.write(data);
+        });
+        // Stream stderr in real-time
+        proc.stderr.on("data", (data) => {
+            process.stderr.write(data);
+        });
+        proc.on("close", (code) => {
+            if (code === 0) {
+                console.log("");
+                console.log("Action completed successfully.");
+                resolve();
+            }
+            else {
+                console.error("");
+                console.error(`Action failed with exit code: ${code}`);
+                process.exit(code || 1);
+            }
+        });
+        proc.on("error", (err) => {
+            console.error(`Failed to execute action: ${err.message}`);
+            reject(err);
+        });
+    });
+}
+function showHelp() {
+    console.log(`
+ralph action - Execute host actions from config.json
+
+USAGE:
+  ralph action [name] [args...]    Execute an action
+  ralph action --list              List available actions
+  ralph action --help              Show this help
+
+OPTIONS:
+  -l, --list      List all configured actions
+  -d, --debug     Show debug output
+  -h, --help      Show this help message
+
+DESCRIPTION:
+  This command executes actions defined in the daemon.actions section of
+  .ralph/config.json. When running inside a container, the action is
+  executed on the host via the daemon. When running on the host directly,
+  the action is executed locally.
+
+  Actions are useful for triggering host operations like:
+  - Building Xcode projects (requires host Xcode installation)
+  - Running deployment scripts
+  - Executing platform-specific tools not available in the container
+
+CONFIGURATION:
+  Define actions in .ralph/config.json:
+
+  {
+    "daemon": {
+      "actions": {
+        "build": {
+          "command": "./scripts/build.sh",
+          "description": "Build the project"
+        },
+        "deploy": {
+          "command": "./scripts/deploy.sh --env staging",
+          "description": "Deploy to staging"
+        },
+        "gen_xcode": {
+          "command": "swift package generate-xcodeproj",
+          "description": "Generate Xcode project from Swift package"
+        }
+      }
+    }
+  }
+
+EXAMPLES:
+  # List available actions
+  ralph action --list
+  ralph action
+
+  # Execute an action
+  ralph action build
+  ralph action deploy --env production
+  ralph action gen_xcode
+
+  # Execute with arguments
+  ralph action build --release
+  ralph action deploy staging
+
+SETUP FOR CONTAINER USAGE:
+  1. Define actions in .ralph/config.json
+  2. Start the daemon on the host: ralph daemon start
+  3. Run the container: ralph docker run
+  4. From inside the container: ralph action build
+
+NOTES:
+  - Actions configured in daemon.actions are automatically available to the daemon
+  - When in a container, the daemon must be running to process action requests
+  - Actions have a 60-second timeout when executed via the daemon
+  - Output is streamed in real-time when executing directly on host
+`);
+}

package/dist/commands/chat.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Chat command for managing Telegram (and other) chat integrations.
+ * Allows ralph to receive commands and send notifications via chat services.
+ */
+/**
+ * Main chat command handler.
+ */
+export declare function chat(args: string[]): Promise<void>;