ralph-cli-sandboxed 0.2.5 → 0.2.7

package/docs/DOCKER.md

@@ -0,0 +1,225 @@
+# Docker Sandbox
+
+Ralph runs AI agents in isolated Docker containers for security. This document covers Docker setup and usage.
+
+## Quick Start
+
+```bash
+# Run container (auto-builds image on first run)
+ralph docker run
+```
+
+> **Note:** `ralph init` automatically creates Docker files in `.ralph/docker/`. Use `ralph docker init` to regenerate them if needed.
+
+## Docker Commands
+
+| Command | Description |
+|---------|-------------|
+| `ralph docker init` | Generate/regenerate Docker configuration files |
+| `ralph docker build` | Build the Docker image |
+| `ralph docker run` | Run ralph inside the container (auto-builds if needed) |
+| `ralph docker shell` | Open an interactive shell in the container |
+| `ralph docker status` | Show container and image status |
+
+## Generated Files
+
+After running `ralph init` or `ralph docker init`, you'll find:
+
+```
+.ralph/docker/
+├── Dockerfile           # Container image definition
+├── docker-compose.yml   # Container orchestration
+└── firewall.sh          # Network sandbox rules
+```
+
+## Features
+
+The Docker setup is based on [Claude Code devcontainer](https://github.com/anthropics/claude-code/tree/main/.devcontainer) and includes:
+
+- **Network sandboxing** - Firewall allows only GitHub, npm, and Anthropic API
+- **Credential mounting** - Your `~/.claude` OAuth credentials are mounted automatically
+- **Language tooling** - Pre-installed based on your selected language
+- **Non-root user** - Runs as `node` user for security
+
+## Customization
+
+### Adding Ports
+
+Edit `.ralph/config.json`:
+
+```json
+{
+  "docker": {
+    "ports": ["3000:3000", "5432:5432"]
+  }
+}
+```
+
+Then regenerate: `ralph docker init`
+
+### Adding Volumes
+
+```json
+{
+  "docker": {
+    "volumes": ["./data:/app/data"]
+  }
+}
+```
+
+### Environment Variables
+
+```json
+{
+  "docker": {
+    "environment": {
+      "NODE_ENV": "development",
+      "DEBUG": "true"
+    }
+  }
+}
+```
+
+### Git Configuration
+
+```json
+{
+  "docker": {
+    "git": {
+      "name": "Your Name",
+      "email": "your@email.com"
+    }
+  }
+}
+```
+
+### Asciinema Recording
+
+Record terminal sessions inside the container for demos, debugging, or sharing AI coding sessions. Recordings are saved as `.cast` files that can be played back with `asciinema play` or uploaded to asciinema.org.
+
+```json
+{
+  "docker": {
+    "asciinema": {
+      "enabled": true,
+      "autoRecord": true,
+      "outputDir": ".recordings"
+    }
+  }
+}
+```
+
+| Setting | Description |
+|---------|-------------|
+| `enabled` | Install asciinema in the container |
+| `autoRecord` | Automatically start recording when container starts |
+| `outputDir` | Directory for recordings (default: `.recordings`) |
+
+After enabling, regenerate Docker files: `ralph docker init`
+
+**Where recordings are stored:**
+
+Recordings are saved to the mounted workspace directory (e.g., `.recordings/`). They never leave the container automatically - no network access is needed.
+
+To upload recordings:
+1. Exit the container
+2. From your host machine: `asciinema upload .recordings/session-*.cast`
+3. Or set `ASCIINEMA_SERVER_URL` environment variable before uploading to use a self-hosted server
+
+**Manual recording** (when `autoRecord: false`):
+
+```bash
+# Inside the container
+asciinema rec .recordings/session.cast     # Start recording
+exit                                        # Stop recording
+
+# After exiting the container, from your host machine:
+asciinema play .recordings/session.cast    # Playback
+asciinema upload .recordings/session.cast  # Upload to asciinema.org
+```
+
+**Auto-recording** (when `autoRecord: true`):
+
+Sessions are automatically recorded to `<outputDir>/session-YYYYMMDD-HHMMSS.cast` when the container starts. Recording stops when you exit the container. Files are available on your host machine in the configured output directory.
+
+### Firewall Configuration
+
+The container firewall allows only specific domains by default: GitHub, npm registry, and Anthropic API. To allow additional domains (e.g., PyPI, internal registries), configure `firewall.allowedDomains`:
+
+```json
+{
+  "docker": {
+    "firewall": {
+      "allowedDomains": ["pypi.org", "files.pythonhosted.org"]
+    }
+  }
+}
+```
+
+After adding domains, regenerate Docker files: `ralph docker init`
+
+The firewall script resolves domains to IPs at container startup using `dig`. Common use cases:
+
+| Use Case | Domains |
+|----------|---------|
+| Python/PyPI | `pypi.org`, `files.pythonhosted.org` |
+| Maven Central | `repo1.maven.org`, `repo.maven.apache.org` |
+| Internal registry | `registry.mycompany.com` |
+
+## Installing Packages
+
+To install additional packages inside the container, run as root:
+
+```bash
+# Update package list and install
+docker compose run -u root ralph apt-get update
+docker compose run -u root ralph apt-get install <package>
+```
+
+For persistent changes, add the installation to the Dockerfile and rebuild:
+
+```bash
+ralph docker build
+```
+
+## Troubleshooting
+
+### Image won't build
+
+Check Docker is running and you have sufficient disk space:
+
+```bash
+docker info
+df -h
+```
+
+### Permission denied errors
+
+The container runs as user `node`. If you have permission issues with mounted volumes:
+
+```bash
+# Fix ownership on host
+sudo chown -R $(id -u):$(id -g) .ralph/
+```
+
+### Network connectivity issues
+
+The firewall script restricts outbound connections. If you need additional access:
+
+1. Edit `.ralph/docker/firewall.sh`
+2. Add your required domains/IPs
+3. Rebuild: `ralph docker build`
+
+### Platform-specific dependencies
+
+If you switch between running on host and in container, reinstall node_modules:
+
+```bash
+rm -rf node_modules && npm install
+```
+
+Or use a separate volume for node_modules:
+
+```bash
+docker run -v $(pwd):/workspace -v /workspace/node_modules your-image
+```

package/docs/HOW-TO-WRITE-PRDs.md

@@ -30,9 +30,11 @@ Use consistent categories to organize your PRD:
 | `bugfix` | Fixing broken behavior |
 | `refactor` | Code improvements without behavior change |
 | `docs` | Documentation updates |
+| `test` | Adding or updating tests |
 | `release` | Version bumps, changelog updates |
 | `config` | Configuration file changes |
-| `test` | Adding or updating tests |
+| `ui` | User interface changes |
+| `integration` | Connecting components, wiring, orchestration |
 
 ## Writing Good Descriptions
 
@@ -200,7 +202,7 @@ Break large features into smaller, independently completable items. Each item sh
 
 ```json
 {
-  "category": "feature|bugfix|docs|release|setup|refactor|config|test",
+  "category": "setup|feature|bugfix|refactor|docs|test|release|config|ui|integration",
   "description": "Imperative verb + specific what + where (context)",
   "steps": [
     "Concrete action with `commands` and file paths",

package/docs/PRD-GENERATOR.md

@@ -92,6 +92,7 @@ If a task takes 2 minutes without thinking, combine with related work.
 | `test` | Test coverage (unit, integration, e2e) |
 | `release` | Version bumps, changelogs, packaging |
 | `config` | Configuration files, settings |
+| `ui` | User interface changes, frontend components |
 | `integration` | Connecting components, wiring, orchestration |
 
 ## Writing Descriptions
@@ -307,7 +308,7 @@ Convert the following document into a Ralph prd.json file.
 
 Rules:
 1. Each sub-task or atomic feature = one PRD item
-2. Use categories: setup, feature, bugfix, refactor, docs, test, release, config, integration
+2. Use categories: setup, feature, bugfix, refactor, docs, test, release, config, ui, integration
 3. Descriptions: imperative verb + specific what + context
 4. Steps: 2-4 concrete actions + verification step
 5. Reference source document sections instead of copying code

package/docs/SECURITY.md

@@ -0,0 +1,78 @@
+# Security
+
+Ralph automates AI agents that execute code and modify files autonomously. This document explains the security model and requirements.
+
+## Container Requirement
+
+**It is strongly recommended to run ralph inside a Docker container for security.** The Ralph Wiggum technique involves running an AI agent autonomously, which means granting it elevated permissions to execute code and modify files without manual approval for each action.
+
+## The `--dangerously-skip-permissions` Flag
+
+When running inside a container, ralph automatically passes the `--dangerously-skip-permissions` flag to Claude Code. This flag:
+
+- Allows Claude to execute commands and modify files without prompting for permission
+- Is **only** enabled when ralph detects it's running inside a container
+- Is required for autonomous operation (otherwise Claude would pause for approval on every action)
+
+**Warning:** The `--dangerously-skip-permissions` flag gives the AI agent full control over the environment. This is why container isolation is critical:
+
+- The container provides a sandbox boundary
+- Network access is restricted to essential services (GitHub, npm, Anthropic API)
+- Your host system remains protected even if something goes wrong
+
+## Container Detection
+
+Ralph detects container environments by checking:
+
+1. `DEVCONTAINER` environment variable
+2. Presence of `/.dockerenv` file
+3. Container indicators in `/proc/1/cgroup` (docker, podman, lxc, containerd)
+4. `container` environment variable (podman, docker)
+
+If you're running outside a container and need autonomous mode, use `ralph docker` to set up a safe sandbox environment first.
+
+## Network Sandboxing
+
+The Docker configuration includes firewall rules limiting network access to:
+
+- **GitHub** - For git operations (clone, push, pull)
+- **npm registry** - For dependency installation
+- **Anthropic API** - For Claude API calls
+
+All other outbound network traffic is blocked by default.
+
+## Credential Handling
+
+### OAuth Credentials (Claude Code)
+
+For Claude Code users with Pro/Max subscriptions, the `~/.claude` directory is mounted into the container:
+
+```yaml
+volumes:
+  - ~/.claude:/home/node/.claude:ro
+```
+
+This allows the AI agent to use your existing OAuth credentials without exposing API keys.
+
+### API Keys
+
+For API key-based authentication, pass environment variables to the container:
+
+```bash
+docker compose run -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY ralph
+```
+
+**Never commit API keys to version control.** Use environment variables or Docker secrets.
+
+## Best Practices
+
+1. **Always use containers** - Never run `ralph run` or `ralph once` outside a container
+2. **Review PRD items** - Check what you're asking the AI to do before running
+3. **Use separate branches** - Let the AI work on feature branches, review before merging
+4. **Monitor progress** - Check `.ralph/progress.txt` and git commits periodically
+5. **Limit scope** - Keep PRD items small and focused to reduce risk
+
+## Reporting Security Issues
+
+If you discover a security vulnerability, please report it by opening an issue at:
+https://github.com/choas/ralph-cli-sandboxed/issues

package/docs/run-state-machine.md

@@ -1,68 +1,77 @@
 # Run Command State Machine
 
 ```mermaid
-stateDiagram-v2
-    [*] --> ParseFlags : run(args)
-
-    ParseFlags --> DetermineMode
-
-    state DetermineMode {
-        [*] --> CheckLoopFlag
-        CheckLoopFlag --> LoopMode : --loop
-        CheckLoopFlag --> CheckIterationArg : no --loop
-        CheckIterationArg --> CountMode : number provided
-        CheckIterationArg --> AllMode : no number (default)
-    }
-
-    DetermineMode --> CheckItems
-
-    state "Check Items" as CheckItems {
-        [*] --> CreateFilteredPRD
-        CreateFilteredPRD --> HasIncomplete
-        HasIncomplete --> StartIteration : yes
-        HasIncomplete --> HandleComplete : no
-    }
-
-    state HandleComplete {
-        [*] --> CheckMode
-        CheckMode --> WaitForNewItems : LoopMode
-        CheckMode --> PrintComplete : AllMode/CountMode
-        WaitForNewItems --> PollLoop
-        PollLoop --> CheckNewItems : every 30s
-        CheckNewItems --> StartIteration : found
-        CheckNewItems --> PollLoop : not found
-        PrintComplete --> [*]
-    }
-
-    state "Start Iteration" as StartIteration
-
-    StartIteration --> RunCLI
-
-    state "Run CLI" as RunCLI {
-        [*] --> SpawnProcess
-        SpawnProcess --> WaitForExit
-        WaitForExit --> ProcessOutput
-    }
-
-    RunCLI --> CheckResult
-
-    state "Check Result" as CheckResult {
-        [*] --> CheckExitCode
-        CheckExitCode --> TrackFailure : non-zero
-        CheckExitCode --> ResetFailures : zero
-        TrackFailure --> CheckConsecutive
-        CheckConsecutive --> StopRun : >= 3 consecutive
-        CheckConsecutive --> CheckCompletionSignal : < 3
-        ResetFailures --> CheckCompletionSignal
-        CheckCompletionSignal --> HandleLoopComplete : COMPLETE signal
-        CheckCompletionSignal --> NextIteration : no signal
-        HandleLoopComplete --> WaitForNewItems : LoopMode
-        HandleLoopComplete --> PrintFinalStatus : AllMode/CountMode
-        StopRun --> [*]
-        PrintFinalStatus --> [*]
-    }
-
-    NextIteration --> CheckIterationLimit
-    CheckIterationLimit --> CheckItems : more iterations
-    CheckIterationLimit --> [*] : limit reached
+flowchart TD
+    subgraph Initialization ["1. Initialization"]
+        Start([Start]) --> ParseArgs[Parse CLI Arguments]
+        ParseArgs --> ModeSelect{Determine Mode}
+
+        ModeSelect -- "--loop flag" --> LoopMode[Loop Mode]
+        ModeSelect -- "number N" --> CountMode[Count Mode]
+        ModeSelect -- "default" --> AllMode[All Mode]
+    end
+
+    subgraph Validation ["2. Item Validation"]
+        CreateFilteredPRD[Create Filtered PRD] --> HasIncomplete{Incomplete Items?}
+
+        HasIncomplete -- "Yes" --> StartIteration
+        HasIncomplete -- "No" --> ModeCheck
+    end
+
+    subgraph Execution ["3. Execution"]
+        StartIteration[Start Iteration] --> SpawnProcess[Spawn CLI Process]
+        SpawnProcess --> MonitorProcess[Monitor & Wait]
+        MonitorProcess --> CaptureResult[Capture Exit Code]
+    end
+
+    subgraph Analysis ["4. Result Analysis"]
+        ExitCheck{Exit Code == 0?}
+
+        ExitCheck -- "No" --> FailurePath[Increment Failure Counter]
+        FailurePath --> CriticalCheck{Failures >= 3?}
+        CriticalCheck -- "Yes" --> Abort([Abort: Too Many Errors])
+        CriticalCheck -- "No" --> SignalCheck
+
+        ExitCheck -- "Yes" --> SuccessPath[Reset Failure Counter]
+        SuccessPath --> SignalCheck
+
+        SignalCheck{COMPLETE Signal?}
+        SignalCheck -- "Yes" --> CompleteModeCheck
+        SignalCheck -- "No" --> IterationCheck
+    end
+
+    subgraph Completion ["5. Completion & Polling"]
+        ModeCheck{Mode?}
+        ModeCheck -- "Loop Mode" --> PollWait
+        ModeCheck -- "All/Count Mode" --> FinalReport
+
+        CompleteModeCheck{Mode?}
+        CompleteModeCheck -- "Loop Mode" --> PollWait[Wait 30 Seconds]
+        CompleteModeCheck -- "All/Count Mode" --> FinalReport[Final Report]
+
+        PollWait --> CheckNewItems{New Items Found?}
+        CheckNewItems -- "Yes" --> StartIteration
+        CheckNewItems -- "No" --> PollWait
+
+        FinalReport --> End([End])
+
+        IterationCheck{Limit Reached?}
+        IterationCheck -- "Yes" --> FinalReport
+        IterationCheck -- "No" --> CreateFilteredPRD
+    end
+
+    %% Cross-subgraph connections
+    LoopMode --> CreateFilteredPRD
+    CountMode --> CreateFilteredPRD
+    AllMode --> CreateFilteredPRD
+    CaptureResult --> ExitCheck
+
+    %% Styling
+    style Initialization fill:#f9f9f9,stroke:#333,stroke-width:2px
+    style Validation fill:#fff4dd,stroke:#d4a017,stroke-width:2px
+    style Execution fill:#e1f5fe,stroke:#01579b,stroke-width:2px
+    style Analysis fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
+    style Completion fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
+    style Abort fill:#ffebee,stroke:#c62828,color:#c62828
+    style End fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-cli-sandboxed",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "AI-driven development automation CLI for Claude Code",
   "type": "module",
   "bin": {