ralph-cli-sandboxed 0.2.5 → 0.2.7

package/README.md

@@ -85,12 +85,28 @@ After running `ralph init`, you'll have:
 
 ### Supported Languages
 
-- **Bun** (TypeScript) - `bun check`, `bun test`
-- **Node.js** (TypeScript) - `npm run typecheck`, `npm test`
-- **Python** - `mypy .`, `pytest`
-- **Go** - `go build ./...`, `go test ./...`
-- **Rust** - `cargo check`, `cargo test`
-- **Custom** - Define your own commands
+Ralph supports 18 programming languages with pre-configured build/test commands:
+
+| Language | Check Command | Test Command |
+|----------|--------------|--------------|
+| Bun (TypeScript) | `bun check` | `bun test` |
+| Node.js (TypeScript) | `npm run typecheck` | `npm test` |
+| Python | `mypy .` | `pytest` |
+| Go | `go build ./...` | `go test ./...` |
+| Rust | `cargo check` | `cargo test` |
+| Java | `mvn compile` | `mvn test` |
+| Kotlin | `gradle build` | `gradle test` |
+| C#/.NET | `dotnet build` | `dotnet test` |
+| Ruby | `bundle exec rubocop` | `bundle exec rspec` |
+| PHP | `composer validate` | `vendor/bin/phpunit` |
+| Swift | `swift build` | `swift test` |
+| Elixir | `mix compile` | `mix test` |
+| Scala | `sbt compile` | `sbt test` |
+| Zig | `zig build` | `zig build test` |
+| Haskell | `stack build` | `stack test` |
+| Clojure | `lein check` | `lein test` |
+| Deno (TypeScript) | `deno check **/*.ts` | `deno test` |
+| Custom | User-defined | User-defined |
 
 ### Supported CLI Providers
 
@@ -147,7 +163,7 @@ The PRD (`prd.json`) is an array of requirements:
 ]
 ```
 
-Categories: `ui`, `feature`, `bugfix`, `setup`, `development`, `testing`, `docs`
+Categories: `setup`, `feature`, `bugfix`, `refactor`, `docs`, `test`, `release`, `config`, `ui`
 
 ### Advanced: File References
 
@@ -191,13 +207,7 @@ Features:
 - Your `~/.claude` credentials mounted automatically (Pro/Max OAuth)
 - Language-specific tooling pre-installed
 
-### Installing packages in container
-
-```bash
-# Run as root to install packages
-docker compose run -u root ralph apt-get update
-docker compose run -u root ralph apt-get install <package>
-```
+See [docs/DOCKER.md](docs/DOCKER.md) for detailed Docker configuration, customization, and troubleshooting.
 
 ## How It Works
 
@@ -212,71 +222,24 @@ When all PRD items pass, Claude outputs `<promise>COMPLETE</promise>` and stops.
 
 ## Security
 
-### 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:
+**It is strongly recommended to run ralph inside a Docker container for security.** The Ralph Wiggum technique involves running an AI agent autonomously with elevated permissions.
 
-- 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)
+When running inside a container, ralph automatically passes `--dangerously-skip-permissions` to Claude Code, allowing autonomous operation. This flag is only enabled in containers for safety.
 
-**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:
-- `DEVCONTAINER` environment variable
-- Presence of `/.dockerenv` file
-- Container indicators in `/proc/1/cgroup`
-- `container` environment variable
-
-If you're running outside a container and need autonomous mode, use `ralph docker` to set up a safe sandbox environment first.
+See [docs/SECURITY.md](docs/SECURITY.md) for detailed security information, container detection, and best practices.
 
 ## Development
 
 To contribute or test changes to ralph locally:
 
 ```bash
-# Clone the repository
 git clone https://github.com/choas/ralph-cli-sandboxed
 cd ralph-cli-sandboxed
-
-# Install dependencies
 npm install
-
-# Run ralph in development mode (without building)
-npm run dev -- <args>
-
-# Examples:
-npm run dev -- --version
-npm run dev -- list
-npm run dev -- once
+npm run dev -- <args>  # Run from TypeScript source
 ```
 
-The `npm run dev -- <args>` command runs ralph directly from TypeScript source using `tsx`, allowing you to test changes without rebuilding.
-
-### Platform-Specific Dependencies
-
-The `node_modules` folder contains platform-specific binaries (e.g., esbuild). If you switch between running on your host machine and inside a Docker/Podman container, you'll need to reinstall dependencies:
-
-```bash
-# When switching environments (host <-> container)
-rm -rf node_modules && npm install
-```
-
-Alternatively, when mounting your project into a container, use a separate volume for node_modules to keep host and container dependencies isolated:
-
-```bash
-podman run -v $(pwd):/workspace -v /workspace/node_modules your-image
-```
+See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed development setup, project structure, and contribution guidelines.
 
 ## Requirements
 

package/dist/commands/docker.js

@@ -1,10 +1,46 @@
-import { existsSync, writeFileSync, mkdirSync, chmodSync } from "fs";
+import { existsSync, writeFileSync, readFileSync, mkdirSync, chmodSync } from "fs";
 import { join, basename } from "path";
 import { spawn } from "child_process";
+import { createHash } from "crypto";
 import { loadConfig, getRalphDir } from "../utils/config.js";
 import { promptConfirm } from "../utils/prompt.js";
 import { getLanguagesJson, getCliProvidersJson } from "../templates/prompts.js";
 const DOCKER_DIR = "docker";
+const CONFIG_HASH_FILE = ".config-hash";
+// Compute hash of docker-relevant config fields
+function computeConfigHash(config) {
+    const relevantConfig = {
+        language: config.language,
+        javaVersion: config.javaVersion,
+        cliProvider: config.cliProvider,
+        docker: config.docker,
+        claude: config.claude,
+    };
+    const content = JSON.stringify(relevantConfig, null, 2);
+    return createHash('sha256').update(content).digest('hex').substring(0, 16);
+}
+// Save config hash to docker directory
+function saveConfigHash(dockerDir, hash) {
+    writeFileSync(join(dockerDir, CONFIG_HASH_FILE), hash + '\n');
+}
+// Load saved config hash, returns null if not found
+function loadConfigHash(dockerDir) {
+    const hashPath = join(dockerDir, CONFIG_HASH_FILE);
+    if (!existsSync(hashPath)) {
+        return null;
+    }
+    return readFileSync(hashPath, 'utf-8').trim();
+}
+// Check if config has changed since last docker init
+function hasConfigChanged(ralphDir, config) {
+    const dockerDir = join(ralphDir, DOCKER_DIR);
+    const savedHash = loadConfigHash(dockerDir);
+    if (!savedHash) {
+        return false; // No hash file means docker init hasn't run yet
+    }
+    const currentHash = computeConfigHash(config);
+    return savedHash !== currentHash;
+}
 // Get language Docker snippet from config, with version substitution
 function getLanguageSnippet(language, javaVersion) {
     const languagesJson = getLanguagesJson();
@@ -36,6 +72,29 @@ function getCliProviderSnippet(cliProvider) {
 function generateDockerfile(language, javaVersion, cliProvider, dockerConfig) {
     const languageSnippet = getLanguageSnippet(language, javaVersion);
     const cliSnippet = getCliProviderSnippet(cliProvider);
+    // Build custom packages section
+    let customPackages = '';
+    if (dockerConfig?.packages && dockerConfig.packages.length > 0) {
+        customPackages = dockerConfig.packages.map(pkg => `    ${pkg} \\`).join('\n') + '\n';
+    }
+    // Build root build commands section
+    let rootBuildCommands = '';
+    if (dockerConfig?.buildCommands?.root && dockerConfig.buildCommands.root.length > 0) {
+        const commands = dockerConfig.buildCommands.root.map(cmd => `RUN ${cmd}`).join('\n');
+        rootBuildCommands = `
+# Custom build commands (root)
+${commands}
+`;
+    }
+    // Build node build commands section
+    let nodeBuildCommands = '';
+    if (dockerConfig?.buildCommands?.node && dockerConfig.buildCommands.node.length > 0) {
+        const commands = dockerConfig.buildCommands.node.map(cmd => `RUN ${cmd}`).join('\n');
+        nodeBuildCommands = `
+# Custom build commands (node user)
+${commands}
+`;
+    }
     // Build git config section if configured
     let gitConfigSection = '';
     if (dockerConfig?.git && (dockerConfig.git.name || dockerConfig.git.email)) {
@@ -51,6 +110,29 @@ function generateDockerfile(language, javaVersion, cliProvider, dockerConfig) {
 RUN ${gitCommands.join(' \\\n    && ')}
 `;
     }
+    // Build asciinema installation section if enabled
+    let asciinemaInstall = '';
+    let asciinemaDir = '';
+    let streamScriptCopy = '';
+    if (dockerConfig?.asciinema?.enabled) {
+        const outputDir = dockerConfig.asciinema.outputDir || '.recordings';
+        asciinemaInstall = `
+# Install asciinema for terminal recording/streaming
+RUN apt-get update && apt-get install -y asciinema && rm -rf /var/lib/apt/lists/*
+`;
+        asciinemaDir = `
+# Create asciinema recordings directory
+RUN mkdir -p /workspace/${outputDir} && chown node:node /workspace/${outputDir}
+`;
+        // Add stream script if streamJson is enabled
+        if (dockerConfig.asciinema.streamJson?.enabled) {
+            streamScriptCopy = `
+# Copy ralph stream wrapper script for clean JSON output
+COPY ralph-stream.sh /usr/local/bin/ralph-stream.sh
+RUN chmod +x /usr/local/bin/ralph-stream.sh
+`;
+        }
+    }
     return `# Ralph CLI Sandbox Environment
 # Based on Claude Code devcontainer
 # Generated by ralph-cli
@@ -85,7 +167,7 @@ RUN apt-get update && apt-get install -y \\
     iproute2 \\
     dnsutils \\
     zsh \\
-    && rm -rf /var/lib/apt/lists/*
+${customPackages}    && rm -rf /var/lib/apt/lists/*
 
 # Setup zsh with oh-my-zsh and plugins (no theme, we set custom prompt)
 RUN sh -c "$(wget -O- https://github.com/deluan/zsh-in-docker/releases/download/v\${ZSH_IN_DOCKER_VERSION}/zsh-in-docker.sh)" -- \\
@@ -130,7 +212,7 @@ RUN echo "node ALL=(ALL) NOPASSWD: /usr/local/bin/init-firewall.sh" >> /etc/sudo
 RUN mkdir -p /workspace && chown node:node /workspace
 RUN mkdir -p /home/node/.claude && chown node:node /home/node/.claude
 RUN mkdir -p /commandhistory && chown node:node /commandhistory
-
+${asciinemaDir}
 # Copy firewall script
 COPY init-firewall.sh /usr/local/bin/init-firewall.sh
 RUN chmod +x /usr/local/bin/init-firewall.sh
@@ -145,17 +227,33 @@ ENV EDITOR=nano
 # Add bash aliases and prompt (fallback if using bash)
 RUN echo 'alias ll="ls -la"' >> /etc/bash.bashrc && \\
     echo 'PS1="\\[\\033[43;30m\\][ralph]\\w\\[\\033[0m\\]\\$ "' >> /etc/bash.bashrc
-
+${rootBuildCommands}${asciinemaInstall}${streamScriptCopy}
 # Switch to non-root user
 USER node
-${gitConfigSection}
+${gitConfigSection}${nodeBuildCommands}
 WORKDIR /workspace
 
 # Default to zsh
 CMD ["zsh"]
 `;
 }
-const FIREWALL_SCRIPT = `#!/bin/bash
+function generateFirewallScript(customDomains = []) {
+    // Generate custom domains section if any are configured
+    let customDomainsSection = '';
+    if (customDomains.length > 0) {
+        const domainList = customDomains.join(' ');
+        customDomainsSection = `
+# Custom allowed domains (from config)
+for ip in $(dig +short ${domainList}); do
+    ipset add allowed_ips $ip 2>/dev/null || true
+done
+`;
+    }
+    // Generate echo line with custom domains if configured
+    const allowedList = customDomains.length > 0
+        ? `GitHub, npm, Anthropic API, local network, ${customDomains.join(', ')}`
+        : 'GitHub, npm, Anthropic API, local network';
+    return `#!/bin/bash
 # Firewall initialization script for Ralph sandbox
 # Based on Claude Code devcontainer firewall
 
@@ -211,7 +309,7 @@ done
 for ip in $(dig +short api.anthropic.com); do
     ipset add allowed_ips $ip 2>/dev/null || true
 done
-
+${customDomainsSection}
 # Allow host network (for mounted volumes, etc.)
 HOST_NETWORK=$(ip route | grep default | awk '{print $3}' | head -1)
 if [ -n "$HOST_NETWORK" ]; then
@@ -232,8 +330,9 @@ iptables -I OUTPUT -p tcp --dport 443 -m set --match-set allowed_ips dst -j ACCE
 iptables -I OUTPUT -p tcp --dport 80 -m set --match-set allowed_ips dst -j ACCEPT
 
 echo "Firewall initialized. Only allowed destinations are accessible."
-echo "Allowed: GitHub, npm, Anthropic API, local network"
+echo "Allowed: ${allowedList}"
 `;
+}
 function generateDockerCompose(imageName, dockerConfig) {
     // Build ports section if configured
     let portsSection = '';
@@ -256,11 +355,15 @@ function generateDockerCompose(imageName, dockerConfig) {
     const volumesSection = baseVolumes.join('\n');
     // Build environment section if configured
     let environmentSection = '';
+    const envEntries = [];
+    // Add user-configured environment variables
     if (dockerConfig?.environment && Object.keys(dockerConfig.environment).length > 0) {
-        const envLines = Object.entries(dockerConfig.environment)
-            .map(([key, value]) => `      - ${key}=${value}`)
-            .join('\n');
-        environmentSection = `    environment:\n${envLines}\n`;
+        for (const [key, value] of Object.entries(dockerConfig.environment)) {
+            envEntries.push(`      - ${key}=${value}`);
+        }
+    }
+    if (envEntries.length > 0) {
+        environmentSection = `    environment:\n${envEntries.join('\n')}\n`;
     }
     else {
         // Keep the commented placeholder for users who don't have config
@@ -268,6 +371,32 @@ function generateDockerCompose(imageName, dockerConfig) {
     # environment:
     #   - ANTHROPIC_API_KEY=\${ANTHROPIC_API_KEY}\n`;
     }
+    // Build command section if configured
+    let commandSection = '';
+    let streamJsonNote = '';
+    if (dockerConfig?.asciinema?.enabled && dockerConfig?.asciinema?.autoRecord) {
+        // Wrap with asciinema recording
+        const outputDir = dockerConfig.asciinema.outputDir || '.recordings';
+        const innerCommand = dockerConfig.startCommand || 'zsh';
+        commandSection = `    command: bash -c "mkdir -p /workspace/${outputDir} && asciinema rec -c '${innerCommand}' /workspace/${outputDir}/session-$$(date +%Y%m%d-%H%M%S).cast"\n`;
+        // Add note about stream-json if enabled
+        if (dockerConfig.asciinema.streamJson?.enabled) {
+            streamJsonNote = `
+    # Stream JSON mode enabled - use ralph-stream.sh for clean Claude output:
+    #   ralph-stream.sh -p "your prompt here"
+    # This formats stream-json output for readable terminal display.
+    # Raw JSON is saved to ${outputDir}/session-*.jsonl for later analysis.
+`;
+        }
+    }
+    else if (dockerConfig?.startCommand) {
+        commandSection = `    command: ${dockerConfig.startCommand}\n`;
+    }
+    else {
+        // Keep the commented placeholder for users who don't have config
+        commandSection = `    # Uncomment to enable firewall sandboxing:
+    # command: bash -c "sudo /usr/local/bin/init-firewall.sh && zsh"\n`;
+    }
     return `# Ralph CLI Docker Compose
 # Generated by ralph-cli
 
@@ -284,9 +413,7 @@ ${environmentSection}    working_dir: /workspace
     tty: true
     cap_add:
       - NET_ADMIN  # Required for firewall
-    # Uncomment to enable firewall sandboxing:
-    # command: bash -c "sudo /usr/local/bin/init-firewall.sh && zsh"
-
+${streamJsonNote}${commandSection}
 volumes:
   ${imageName}-history:
 `;
@@ -297,19 +424,115 @@ dist
 .git
 *.log
 `;
-async function generateFiles(ralphDir, language, imageName, force = false, javaVersion, cliProvider, dockerConfig) {
+// Generate stream wrapper script for clean asciinema recordings
+function generateStreamScript(outputDir, saveRawJson) {
+    const saveJsonSection = saveRawJson ? `
+# Save raw JSON for later analysis
+JSON_LOG="$OUTPUT_DIR/session-$TIMESTAMP.jsonl"
+TEE_CMD="tee \\"$JSON_LOG\\""` : `
+TEE_CMD="cat"`;
+    return `#!/bin/bash
+# Ralph stream wrapper - formats Claude stream-json output for clean terminal display
+# Generated by ralph-cli
+
+set -e
+
+OUTPUT_DIR="\${RALPH_RECORDING_DIR:-/workspace/${outputDir}}"
+TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+
+# Ensure output directory exists
+mkdir -p "$OUTPUT_DIR"
+${saveJsonSection}
+
+# jq filter to extract and format content from stream-json
+# Handles text, tool calls, tool results, file operations, and commands
+JQ_FILTER='
+  if .type == "content_block_delta" then
+    (if .delta.type == "text_delta" then .delta.text // empty
+     elif .delta.text then .delta.text
+     else empty end)
+  elif .type == "content_block_start" then
+    (if .content_block.type == "tool_use" then "\\n── Tool: " + (.content_block.name // "unknown") + " ──\\n"
+     elif .content_block.type == "text" then .content_block.text // empty
+     else empty end)
+  elif .type == "tool_result" then
+    "\\n── Tool Result ──\\n" + ((.content // .output // "") | tostring) + "\\n"
+  elif .type == "assistant" then
+    ([.message.content[]? | select(.type == "text") | .text] | join(""))
+  elif .type == "message_start" then
+    "\\n"
+  elif .type == "message_delta" then
+    (if .delta.stop_reason then "\\n[" + .delta.stop_reason + "]\\n" else empty end)
+  elif .type == "file_edit" or .type == "file_write" then
+    "\\n── Writing: " + (.path // .file // "unknown") + " ──\\n"
+  elif .type == "file_read" then
+    "── Reading: " + (.path // .file // "unknown") + " ──\\n"
+  elif .type == "bash" or .type == "command" then
+    "\\n── Running: " + (.command // .content // "") + " ──\\n"
+  elif .type == "bash_output" or .type == "command_output" then
+    (.output // .content // "") + "\\n"
+  elif .type == "result" then
+    (if .result then "\\n── Result ──\\n" + (.result | tostring) + "\\n" else empty end)
+  elif .type == "error" then
+    "\\n[Error] " + (.error.message // (.error | tostring)) + "\\n"
+  elif .type == "system" then
+    (if .message then "[System] " + .message + "\\n" else empty end)
+  elif .text then
+    .text
+  elif (.content | type) == "string" then
+    .content
+  else
+    empty
+  end
+'
+
+# Pass all arguments to claude with stream-json output
+# Filter JSON lines, optionally save raw JSON, and display formatted text
+claude \\
+  --output-format stream-json \\
+  --verbose \\
+  --print \\
+  "\$@" 2>&1 \\
+| grep --line-buffered '^{' \\
+| eval $TEE_CMD \\
+| jq --unbuffered -rj "$JQ_FILTER"
+
+echo ""  # Ensure final newline
+`;
+}
+// Generate .mcp.json content for Claude Code MCP servers
+function generateMcpJson(mcpServers) {
+    return JSON.stringify({ mcpServers }, null, 2);
+}
+// Generate skill file content with YAML frontmatter
+function generateSkillFile(skill) {
+    const lines = ['---', `description: ${skill.description}`];
+    if (skill.userInvocable === false) {
+        lines.push('user-invocable: false');
+    }
+    lines.push('---', '', skill.instructions, '');
+    return lines.join('\n');
+}
+async function generateFiles(ralphDir, language, imageName, force = false, javaVersion, cliProvider, dockerConfig, claudeConfig) {
     const dockerDir = join(ralphDir, DOCKER_DIR);
     // Create docker directory
     if (!existsSync(dockerDir)) {
         mkdirSync(dockerDir, { recursive: true });
         console.log(`Created ${DOCKER_DIR}/`);
     }
+    const customDomains = dockerConfig?.firewall?.allowedDomains || [];
     const files = [
         { name: "Dockerfile", content: generateDockerfile(language, javaVersion, cliProvider, dockerConfig) },
-        { name: "init-firewall.sh", content: FIREWALL_SCRIPT },
+        { name: "init-firewall.sh", content: generateFirewallScript(customDomains) },
         { name: "docker-compose.yml", content: generateDockerCompose(imageName, dockerConfig) },
         { name: ".dockerignore", content: DOCKERIGNORE },
     ];
+    // Add stream script if streamJson is enabled
+    if (dockerConfig?.asciinema?.enabled && dockerConfig.asciinema.streamJson?.enabled) {
+        const outputDir = dockerConfig.asciinema.outputDir || '.recordings';
+        const saveRawJson = dockerConfig.asciinema.streamJson.saveRawJson !== false; // default true
+        files.push({ name: "ralph-stream.sh", content: generateStreamScript(outputDir, saveRawJson) });
+    }
     for (const file of files) {
         const filePath = join(dockerDir, file.name);
         if (existsSync(filePath) && !force) {
@@ -325,6 +548,58 @@ async function generateFiles(ralphDir, language, imageName, force = false, javaV
         }
         console.log(`Created ${DOCKER_DIR}/${file.name}`);
     }
+    // Generate Claude config files at project root
+    const projectRoot = process.cwd();
+    // Generate .mcp.json if MCP servers are configured
+    if (claudeConfig?.mcpServers && Object.keys(claudeConfig.mcpServers).length > 0) {
+        const mcpJsonPath = join(projectRoot, '.mcp.json');
+        if (existsSync(mcpJsonPath) && !force) {
+            const overwrite = await promptConfirm('.mcp.json already exists. Overwrite?');
+            if (!overwrite) {
+                console.log('Skipped .mcp.json');
+            }
+            else {
+                writeFileSync(mcpJsonPath, generateMcpJson(claudeConfig.mcpServers));
+                console.log('Created .mcp.json');
+            }
+        }
+        else {
+            writeFileSync(mcpJsonPath, generateMcpJson(claudeConfig.mcpServers));
+            console.log('Created .mcp.json');
+        }
+    }
+    // Generate skill files if skills are configured
+    if (claudeConfig?.skills && claudeConfig.skills.length > 0) {
+        const commandsDir = join(projectRoot, '.claude', 'commands');
+        if (!existsSync(commandsDir)) {
+            mkdirSync(commandsDir, { recursive: true });
+            console.log('Created .claude/commands/');
+        }
+        for (const skill of claudeConfig.skills) {
+            const skillPath = join(commandsDir, `${skill.name}.md`);
+            if (existsSync(skillPath) && !force) {
+                const overwrite = await promptConfirm(`.claude/commands/${skill.name}.md already exists. Overwrite?`);
+                if (!overwrite) {
+                    console.log(`Skipped .claude/commands/${skill.name}.md`);
+                    continue;
+                }
+            }
+            writeFileSync(skillPath, generateSkillFile(skill));
+            console.log(`Created .claude/commands/${skill.name}.md`);
+        }
+    }
+    // Save config hash for change detection
+    const configForHash = {
+        language,
+        checkCommand: '',
+        testCommand: '',
+        javaVersion,
+        cliProvider,
+        docker: dockerConfig,
+        claude: claudeConfig,
+    };
+    const hash = computeConfigHash(configForHash);
+    saveConfigHash(dockerDir, hash);
 }
 async function buildImage(ralphDir) {
     const dockerDir = join(ralphDir, DOCKER_DIR);
@@ -332,9 +607,17 @@ async function buildImage(ralphDir) {
         console.error("Dockerfile not found. Run 'ralph docker' first.");
         process.exit(1);
     }
-    console.log("Building Docker image...\n");
-    // Get image name for compose project name
+    // Get config and check for changes
     const config = loadConfig();
+    // Check if config has changed since last docker init
+    if (hasConfigChanged(ralphDir, config)) {
+        const regenerate = await promptConfirm("Config has changed since last docker init. Regenerate Docker files?");
+        if (regenerate) {
+            await generateFiles(ralphDir, config.language, config.imageName || `ralph-${basename(process.cwd()).toLowerCase().replace(/[^a-z0-9-]/g, "-")}`, true, config.javaVersion, config.cliProvider, config.docker, config.claude);
+            console.log("");
+        }
+    }
+    console.log("Building Docker image...\n");
     const imageName = config.imageName || `ralph-${basename(process.cwd()).toLowerCase().replace(/[^a-z0-9-]/g, "-")}`;
     return new Promise((resolve, reject) => {
         // Use --no-cache and --pull to ensure we always get the latest CLI versions
@@ -398,15 +681,34 @@ function getCliProviderConfig(cliProvider) {
         modelConfig: provider.modelConfig,
     };
 }
-async function runContainer(ralphDir, imageName, language, javaVersion, cliProvider, dockerConfig) {
+async function runContainer(ralphDir, imageName, language, javaVersion, cliProvider, dockerConfig, claudeConfig) {
     const dockerDir = join(ralphDir, DOCKER_DIR);
     const dockerfileExists = existsSync(join(dockerDir, "Dockerfile"));
     const hasImage = await imageExists(imageName);
+    // Check if config has changed since last docker init
+    if (dockerfileExists) {
+        const configForHash = {
+            language,
+            checkCommand: '',
+            testCommand: '',
+            javaVersion,
+            cliProvider,
+            docker: dockerConfig,
+            claude: claudeConfig,
+        };
+        if (hasConfigChanged(ralphDir, configForHash)) {
+            const regenerate = await promptConfirm("Config has changed since last docker init. Regenerate Docker files?");
+            if (regenerate) {
+                await generateFiles(ralphDir, language, imageName, true, javaVersion, cliProvider, dockerConfig, claudeConfig);
+                console.log("");
+            }
+        }
+    }
     // Auto-init and build if docker folder or image doesn't exist
     if (!dockerfileExists || !hasImage) {
         if (!dockerfileExists) {
             console.log("Docker folder not found. Initializing docker setup...\n");
-            await generateFiles(ralphDir, language, imageName, true, javaVersion, cliProvider, dockerConfig);
+            await generateFiles(ralphDir, language, imageName, true, javaVersion, cliProvider, dockerConfig, claudeConfig);
             console.log("");
         }
         if (!hasImage) {
@@ -654,7 +956,7 @@ export async function dockerInit(silent = false) {
         console.log(`CLI provider: ${config.cliProvider}`);
     }
     console.log(`Image name: ${imageName}\n`);
-    await generateFiles(ralphDir, config.language, imageName, true, config.javaVersion, config.cliProvider, config.docker);
+    await generateFiles(ralphDir, config.language, imageName, true, config.javaVersion, config.cliProvider, config.docker, config.claude);
     if (!silent) {
         console.log(`
 Docker files generated in .ralph/docker/
@@ -681,6 +983,7 @@ USAGE:
   ralph docker init -y      Generate files, overwrite without prompting
   ralph docker build        Build image (fetches latest CLI versions)
   ralph docker build --clean  Clean existing image and rebuild from scratch
+                              (alias: --no-cache)
   ralph docker run          Run container (auto-init and build if needed)
   ralph docker clean        Remove Docker image and associated resources
   ralph docker help         Show this help message
@@ -735,14 +1038,15 @@ INSTALLING PACKAGES (works with Docker & Podman):
     switch (subcommand) {
         case "build":
             // Handle build --clean combination: clean first, then build
-            if (hasFlag("--clean")) {
+            // Also support --no-cache as alias for --clean
+            if (hasFlag("--clean") || hasFlag("--no-cache") || hasFlag("-no-cache")) {
                 await cleanImage(imageName, ralphDir);
                 console.log(""); // Add spacing between clean and build output
             }
             await buildImage(ralphDir);
             break;
         case "run":
-            await runContainer(ralphDir, imageName, config.language, config.javaVersion, config.cliProvider, config.docker);
+            await runContainer(ralphDir, imageName, config.language, config.javaVersion, config.cliProvider, config.docker, config.claude);
             break;
         case "clean":
             await cleanImage(imageName, ralphDir);
@@ -761,7 +1065,7 @@ INSTALLING PACKAGES (works with Docker & Podman):
                 console.log(`CLI provider: ${config.cliProvider}`);
             }
             console.log(`Image name: ${imageName}\n`);
-            await generateFiles(ralphDir, config.language, imageName, force, config.javaVersion, config.cliProvider, config.docker);
+            await generateFiles(ralphDir, config.language, imageName, force, config.javaVersion, config.cliProvider, config.docker, config.claude);
             console.log(`
 Docker files generated in .ralph/docker/
 

package/dist/commands/help.js

@@ -56,6 +56,7 @@ DOCKER SUBCOMMANDS:
 
 EXAMPLES:
   ralph init                 # Initialize ralph (interactive CLI, language, tech selection)
+  ralph init -y              # Initialize with defaults (Claude + Node.js, no prompts)
   ralph once                 # Run single iteration
   ralph run                  # Run until all tasks complete (default)
   ralph run 5                # Run exactly 5 iterations

package/dist/commands/init.d.ts

@@ -1 +1 @@
-export declare function init(_args: string[]): Promise<void>;
+export declare function init(args: string[]): Promise<void>;