ralph-cli-sandboxed 0.4.0 → 0.4.2

package/docs/chat-architecture.md

@@ -0,0 +1,251 @@
+# Ralph Chat Architecture
+
+## Overview
+
+The Ralph CLI chat system enables external control of Ralph projects via chat platforms (Slack, Discord, Telegram). It consists of two main components that communicate via a file-based message queue.
+
+## High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              SLACK / DISCORD                                 │
+│                                                                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐ │
+│  │ /ralph cmd   │  │ @bot mention │  │ @qa @review  │  │ Thread replies   │ │
+│  │ (slash cmd)  │  │ (app_mention)│  │ (responders) │  │ (continuation)   │ │
+│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘ │
+└─────────┼─────────────────┼─────────────────┼───────────────────┼───────────┘
+          │                 │                 │                   │
+          ▼                 ▼                 ▼                   ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         HOST: ralph chat start                               │
+│                                                                              │
+│  ┌───────────────────────────────────────────────────────────────────────┐  │
+│  │                        CHAT PROVIDER (Slack/Discord)                   │  │
+│  │                                                                        │  │
+│  │  ┌─────────────┐    ┌─────────────────┐    ┌──────────────────────┐   │  │
+│  │  │ Event       │───▶│ ResponderMatcher │───▶│ Thread Conversations │   │  │
+│  │  │ Handlers    │    │ (@qa, @review)   │    │ (multi-turn memory)  │   │  │
+│  │  └─────────────┘    └────────┬────────┘    └──────────────────────┘   │  │
+│  │                              │                                         │  │
+│  └──────────────────────────────┼─────────────────────────────────────────┘  │
+│                                 │                                            │
+│         ┌───────────────────────┼───────────────────────┐                    │
+│         ▼                       ▼                       ▼                    │
+│  ┌─────────────┐    ┌───────────────────┐    ┌───────────────────┐          │
+│  │ LLM         │    │ Claude Code       │    │ CLI Responder     │          │
+│  │ Responder   │    │ Responder         │    │ (shell commands)  │          │
+│  │             │    │                   │    │                   │          │
+│  │ ┌─────────┐ │    │ claude -p "..."   │    │ eslint, etc.      │          │
+│  │ │Anthropic│ │    │ --print           │    │                   │          │
+│  │ │ OpenAI  │ │    │                   │    │                   │          │
+│  │ └─────────┘ │    └───────────────────┘    └───────────────────┘          │
+│  │             │                                                             │
+│  │ ┌─────────┐ │                                                             │
+│  │ │Git Diff │ │    /ralph commands (run, status, exec, etc.)                │
+│  │ │Keywords │ │                    │                                        │
+│  │ └─────────┘ │                    ▼                                        │
+│  └─────────────┘    ┌───────────────────────────────────────┐               │
+│                     │           Command Handler              │               │
+│                     │  run, stop, status, exec, add, claude  │               │
+│                     └───────────────────┬───────────────────┘               │
+│                                         │                                    │
+│                                         ▼                                    │
+│                     ┌───────────────────────────────────────┐               │
+│                     │         .ralph/messages.json           │               │
+│                     │         (Message Queue)                │               │
+│                     └───────────────────┬───────────────────┘               │
+└─────────────────────────────────────────┼────────────────────────────────────┘
+                                          │
+                    ══════════════════════╪══════════════════════
+                          DOCKER BOUNDARY │ (volume mount)
+                    ══════════════════════╪══════════════════════
+                                          │
+┌─────────────────────────────────────────┼────────────────────────────────────┐
+│                                         ▼                                    │
+│                     ┌───────────────────────────────────────┐               │
+│                     │    /workspace/.ralph/messages.json     │               │
+│                     │         (same file via mount)          │               │
+│                     └───────────────────┬───────────────────┘               │
+│                                         │                                    │
+│                                         ▼                                    │
+│                     ┌───────────────────────────────────────┐               │
+│                     │         ralph listen                   │               │
+│                     │    (polls for pending messages)        │               │
+│                     └───────────────────┬───────────────────┘               │
+│                                         │                                    │
+│         ┌───────────────────────────────┼───────────────────┐               │
+│         ▼                               ▼                   ▼               │
+│  ┌─────────────┐            ┌───────────────┐      ┌─────────────┐          │
+│  │ ralph run   │            │ exec command  │      │ ralph       │          │
+│  │ --category  │            │ (shell)       │      │ status      │          │
+│  └─────────────┘            └───────────────┘      └─────────────┘          │
+│                                                                              │
+│                         CONTAINER: ralph listen                              │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Responder Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Message: "@review last"                       │
+└─────────────────────────────┬───────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    ResponderMatcher                              │
+│                                                                  │
+│  1. Check @mention triggers: @qa, @review, @explain, @code      │
+│  2. Check keyword triggers: !lint, help                          │
+│  3. Fall back to default responder                               │
+└─────────────────────────────┬───────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Match: @review → "reviewer"                   │
+│                    Args: "last"                                  │
+└─────────────────────────────┬───────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    LLM Responder                                 │
+│                                                                  │
+│  1. Detect git keyword: "last" → git show HEAD                  │
+│  2. Fetch git diff content                                       │
+│  3. Build message with diff                                      │
+│  4. Load conversation history (if thread)                        │
+│  5. Send to LLM (Anthropic/OpenAI)                              │
+│  6. Log to .ralph/logs/responder-YYYY-MM-DD.log                 │
+│  7. Return response                                              │
+└─────────────────────────────┬───────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Store in Thread Conversation                  │
+│                                                                  │
+│  threadConversations.set(threadTs, {                            │
+│    responderName: "reviewer",                                    │
+│    messages: [                                                   │
+│      { role: "user", content: "..." },                          │
+│      { role: "assistant", content: "..." }                       │
+│    ]                                                             │
+│  })                                                              │
+└─────────────────────────────┬───────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Reply in Slack Thread                         │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Thread Conversation Flow
+
+```
+Thread Start                    Thread Continuation
+─────────────                   ───────────────────
+
+User: @review diff              User: What about security?
+        │                               │
+        ▼                               ▼
+ResponderMatcher              Check threadConversations
+matches "@review"             ─────────────────────────
+        │                     Found existing conversation
+        ▼                     for this thread_ts
+Execute LLM with                        │
+git diff content                        ▼
+        │                     Execute LLM with:
+        ▼                     - Previous messages (history)
+Store conversation            - New user message
+in threadConversations                  │
+        │                               ▼
+        ▼                     Append to conversation
+Reply in thread               history (max 20 messages)
+                                        │
+                                        ▼
+                              Reply in thread
+```
+
+## Message Queue Format
+
+```json
+{
+  "messages": [
+    {
+      "id": "uuid-1234",
+      "from": "host",
+      "action": "run",
+      "args": ["feature"],
+      "timestamp": 1706789012345,
+      "status": "pending"
+    },
+    {
+      "id": "uuid-1234",
+      "from": "host",
+      "action": "run",
+      "args": ["feature"],
+      "timestamp": 1706789012345,
+      "status": "done",
+      "response": {
+        "success": true,
+        "output": "Ralph run started (category: feature)"
+      }
+    }
+  ]
+}
+```
+
+## Git Diff Keywords
+
+| Keyword | Git Command | Description |
+|---------|-------------|-------------|
+| `diff` / `changes` | `git diff` | Unstaged changes |
+| `staged` | `git diff --cached` | Staged changes |
+| `last` / `last commit` | `git show HEAD` | Last commit |
+| `all` | `git diff HEAD` | All uncommitted |
+| `HEAD~N` | `git show HEAD~N` | N commits ago |
+
+## Responder Types
+
+| Type | Description | Example Trigger |
+|------|-------------|-----------------|
+| `llm` | Send to LLM (Anthropic/OpenAI) | `@qa`, `@review` |
+| `claude-code` | Spawn Claude Code CLI | `@code` |
+| `cli` | Run shell command | `!lint` |
+
+## Configuration
+
+```json
+{
+  "chat": {
+    "provider": "slack",
+    "slack": {
+      "botToken": "xoxb-...",
+      "appToken": "xapp-...",
+      "signingSecret": "...",
+      "allowedChannelIds": ["C1234567890"]
+    },
+    "responders": {
+      "qa": {
+        "type": "llm",
+        "trigger": "@qa",
+        "provider": "anthropic",
+        "systemPrompt": "You are a QA assistant for {{project}}..."
+      }
+    }
+  }
+}
+```
+
+## File Locations
+
+```
+Host Machine                          Container
+────────────                          ─────────
+.ralph/
+├── config.json                       /workspace/.ralph/
+├── chat-state.json                   ├── messages.json (shared)
+├── messages.json ◄──── mount ────►   ├── run.pid
+└── logs/                             └── ...
+    └── responder-YYYY-MM-DD.log
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-cli-sandboxed",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "AI-driven development automation CLI for Claude Code",
   "type": "module",
   "bin": {
@@ -17,19 +17,29 @@
     "copy-config": "mkdir -p dist/config && cp src/config/*.json dist/config/",
     "dev": "npx tsx src/index.ts",
     "typecheck": "tsc --noEmit",
+    "lint": "oxlint src/",
+    "format": "oxfmt src/",
+    "format:check": "oxfmt --check src/",
     "prepublishOnly": "npm run build",
     "prepare": "npm run build"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
     "@inkjs/ui": "^2.0.0",
+    "@slack/bolt": "^4.6.0",
+    "@slack/web-api": "^7.13.0",
+    "discord.js": "^14.16.0",
     "ink": "^5.0.1",
     "ink-text-input": "^6.0.0",
+    "openai": "^4.77.0",
     "react": "^18.3.1",
     "readline": "^1.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "@types/react": "^18.3.12",
+    "oxfmt": "^0.27.0",
+    "oxlint": "^1.42.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"
   },
@@ -57,5 +67,8 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "overrides": {
+    "undici": "^6.23.0"
   }
 }