ralph-cli-sandboxed 0.2.8 → 0.3.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
 {
-  "notifyCommand": "ntfy pub mytopic"
+  "notifications": {
+    "provider": "ntfy",
+    "ntfy": {
+      "topic": "my-ralph-notifications",
+      "server": "https://ntfy.sh"
+    }
+  }
 }
 ```
 
-The message is appended as the last argument to your command. Supported notification tools include:
+| 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
+{
+  "notifications": {
+    "provider": "command",
+    "command": "notify-send Ralph"
+  }
+}
+```
+
+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
+
+# Terminal 2: Run container
+ralph docker run
 
-# 2. Subscribe to your topic on your phone (ntfy app) or browser
-# Visit: https://ntfy.sh/your-unique-topic
+# 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.
+
+#### Custom Daemon Actions
 
-# 3. Configure ralph
-# In .ralph/config.json:
+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
@@ -196,6 +280,36 @@ 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.
 
+### Skills Configuration
+
+Skills are reusable instruction sets that extend Claude's behavior for specific languages or project requirements. They inject additional context and rules into prompts.
+
+Configure skills in `.ralph/config.json`:
+
+```json
+{
+  "claude": {
+    "skills": [
+      {
+        "name": "swift-main-naming",
+        "description": "Prevents naming files main.swift when using @main attribute",
+        "instructions": "IMPORTANT: In Swift, files with @main attribute MUST NOT be named main.swift...",
+        "userInvocable": false
+      }
+    ]
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `name` | Unique skill identifier (kebab-case) |
+| `description` | Brief description shown during selection |
+| `instructions` | Full instructions injected into Claude's prompt |
+| `userInvocable` | If `true`, user can invoke via `/skill-name` (default: `true`) |
+
+During `ralph init`, you can select built-in skills for your chosen language. See [docs/SKILLS.md](docs/SKILLS.md) for detailed configuration, custom skills, and best practices.
+
 ### 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.

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>;