ralph-cli-claude 0.1.1 → 0.1.3

package/README.md

@@ -140,6 +140,59 @@ Generates `ralph.sh` and `ralph-once.sh` in your project root.
 
 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:
+
+- 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:
+- `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.
+
+## Development
+
+To contribute or test changes to ralph locally:
+
+```bash
+# Clone the repository
+git clone https://github.com/anthropics/ralph-cli-claude
+cd ralph-cli-claude
+
+# Install dependencies
+npm install
+
+# Run ralph in development mode (without building)
+npm run dev -- <args>
+
+# Examples:
+npm run dev -- --version
+npm run dev -- prd list
+npm run dev -- once
+```
+
+The `npm run dev -- <args>` command runs ralph directly from TypeScript source using `tsx`, allowing you to test changes without rebuilding.
+
 ## Requirements
 
 - Node.js 18+

package/dist/commands/docker.js

@@ -281,9 +281,10 @@ async function buildImage(ralphDir) {
         console.error("Dockerfile not found. Run 'ralph docker' first.");
         process.exit(1);
     }
-    console.log("Building Docker image...\n");
+    console.log("Building Docker image (fetching latest Claude Code)...\n");
     return new Promise((resolve, reject) => {
-        const proc = spawn("docker", ["compose", "build"], {
+        // Use --no-cache and --pull to ensure we always get the latest Claude Code version
+        const proc = spawn("docker", ["compose", "build", "--no-cache", "--pull"], {
             cwd: dockerDir,
             stdio: "inherit",
         });
@@ -336,7 +337,7 @@ ralph docker - Generate and manage Docker sandbox environment
 USAGE:
   ralph docker              Generate Dockerfile and scripts
   ralph docker -y           Generate files, overwrite without prompting
-  ralph docker --build      Build the Docker image
+  ralph docker --build      Build image (always fetches latest Claude Code)
   ralph docker --run        Run container with project mounted
 
 FILES GENERATED:

package/dist/commands/prd.js

@@ -121,22 +121,51 @@ function toggle(args) {
         console.log(`Toggled all ${prd.length} PRD entries.`);
         return;
     }
-    const index = parseInt(arg);
-    if (!index || isNaN(index)) {
-        console.error("Usage: ralph prd toggle <number>");
+    // Parse all numeric arguments
+    const indices = [];
+    for (const a of args) {
+        const index = parseInt(a);
+        if (!index || isNaN(index)) {
+            console.error("Usage: ralph prd toggle <number> [number2] [number3] ...");
+            console.error("       ralph prd toggle --all");
+            process.exit(1);
+        }
+        indices.push(index);
+    }
+    if (indices.length === 0) {
+        console.error("Usage: ralph prd toggle <number> [number2] [number3] ...");
         console.error("       ralph prd toggle --all");
         process.exit(1);
     }
     const prd = loadPrd();
-    if (index < 1 || index > prd.length) {
-        console.error(`Invalid entry number. Must be 1-${prd.length}`);
-        process.exit(1);
+    // Validate all indices
+    for (const index of indices) {
+        if (index < 1 || index > prd.length) {
+            console.error(`Invalid entry number: ${index}. Must be 1-${prd.length}`);
+            process.exit(1);
+        }
+    }
+    // Toggle each entry
+    for (const index of indices) {
+        const entry = prd[index - 1];
+        entry.passes = !entry.passes;
+        const statusText = entry.passes ? "PASSING" : "NOT PASSING";
+        console.log(`Entry #${index} "${entry.description}" is now ${statusText}`);
     }
-    const entry = prd[index - 1];
-    entry.passes = !entry.passes;
     savePrd(prd);
-    const statusText = entry.passes ? "PASSING" : "NOT PASSING";
-    console.log(`Entry #${index} "${entry.description}" is now ${statusText}`);
+}
+function clean() {
+    const prd = loadPrd();
+    const originalLength = prd.length;
+    const filtered = prd.filter((entry) => !entry.passes);
+    if (filtered.length === originalLength) {
+        console.log("No passing entries to clean.");
+        return;
+    }
+    const removed = originalLength - filtered.length;
+    savePrd(filtered);
+    console.log(`Removed ${removed} passing ${removed === 1 ? "entry" : "entries"}.`);
+    console.log(`${filtered.length} ${filtered.length === 1 ? "entry" : "entries"} remaining.`);
 }
 export async function prd(args) {
     const subcommand = args[0];
@@ -153,14 +182,18 @@ export async function prd(args) {
         case "toggle":
             toggle(args.slice(1));
             break;
+        case "clean":
+            clean();
+            break;
         default:
-            console.error("Usage: ralph prd <add|list|status|toggle>");
+            console.error("Usage: ralph prd <add|list|status|toggle|clean>");
             console.error("\nSubcommands:");
             console.error("  add              Add a new PRD entry");
             console.error("  list             List all PRD entries");
             console.error("  status           Show completion status");
-            console.error("  toggle <n>       Toggle passes status for entry n");
+            console.error("  toggle <n> ...   Toggle passes status for entry n (accepts multiple)");
             console.error("  toggle --all     Toggle all PRD entries");
+            console.error("  clean            Remove all passing entries from the PRD");
             process.exit(1);
     }
 }

package/dist/commands/run.js

@@ -1,6 +1,8 @@
 import { spawn } from "child_process";
-import { existsSync, readFileSync } from "fs";
-import { checkFilesExist, loadPrompt, getPaths } from "../utils/config.js";
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { checkFilesExist, loadConfig, loadPrompt, getPaths } from "../utils/config.js";
 /**
  * Detects if we're running inside a container (Docker or Podman).
  * This is used to determine whether to pass --dangerously-skip-permissions to claude.
@@ -30,7 +32,22 @@ function isRunningInContainer() {
     }
     return false;
 }
-async function runIteration(prompt, paths, sandboxed) {
+/**
+ * Creates a filtered PRD file containing only incomplete items (passes: false).
+ * Returns the path to the temp file, or null if all items pass.
+ */
+function createFilteredPrd(prdPath) {
+    const content = readFileSync(prdPath, "utf-8");
+    const items = JSON.parse(content);
+    const incompleteItems = items.filter(item => item.passes === false);
+    const tempPath = join(tmpdir(), `ralph-prd-filtered-${Date.now()}.json`);
+    writeFileSync(tempPath, JSON.stringify(incompleteItems, null, 2));
+    return {
+        tempPath,
+        hasIncomplete: incompleteItems.length > 0
+    };
+}
+async function runIteration(prompt, paths, sandboxed, filteredPrdPath) {
     return new Promise((resolve, reject) => {
         let output = "";
         // Build claude arguments
@@ -39,10 +56,10 @@ async function runIteration(prompt, paths, sandboxed) {
         if (sandboxed) {
             claudeArgs.push("--dangerously-skip-permissions");
         }
-        claudeArgs.push("-p", `@${paths.prd} @${paths.progress} ${prompt}`);
+        // Use the filtered PRD (only incomplete items) for the prompt
+        claudeArgs.push("-p", `@${filteredPrdPath} @${paths.progress} ${prompt}`);
         const proc = spawn("claude", claudeArgs, {
             stdio: ["inherit", "pipe", "inherit"],
-            shell: true,
         });
         proc.stdout.on("data", (data) => {
             const chunk = data.toString();
@@ -65,6 +82,7 @@ export async function run(args) {
         process.exit(1);
     }
     checkFilesExist();
+    const config = loadConfig();
     const prompt = loadPrompt();
     const paths = getPaths();
     // Check if we're running in a sandboxed container environment
@@ -73,28 +91,62 @@ export async function run(args) {
     if (sandboxed) {
         console.log("Detected container environment - running with --dangerously-skip-permissions\n");
     }
-    for (let i = 1; i <= iterations; i++) {
-        console.log(`\n${"=".repeat(50)}`);
-        console.log(`Iteration ${i} of ${iterations}`);
-        console.log(`${"=".repeat(50)}\n`);
-        const { exitCode, output } = await runIteration(prompt, paths, sandboxed);
-        if (exitCode !== 0) {
-            console.error(`\nClaude exited with code ${exitCode}`);
-            console.log("Continuing to next iteration...");
+    // Track temp file for cleanup
+    let filteredPrdPath = null;
+    try {
+        for (let i = 1; i <= iterations; i++) {
+            console.log(`\n${"=".repeat(50)}`);
+            console.log(`Iteration ${i} of ${iterations}`);
+            console.log(`${"=".repeat(50)}\n`);
+            // Create a fresh filtered PRD for each iteration (in case items were completed)
+            const { tempPath, hasIncomplete } = createFilteredPrd(paths.prd);
+            filteredPrdPath = tempPath;
+            if (!hasIncomplete) {
+                console.log("\n" + "=".repeat(50));
+                console.log("PRD COMPLETE - All features already implemented!");
+                console.log("=".repeat(50));
+                break;
+            }
+            console.log(`Filtered PRD: sending only incomplete items to Claude\n`);
+            const { exitCode, output } = await runIteration(prompt, paths, sandboxed, filteredPrdPath);
+            // Clean up temp file after each iteration
+            try {
+                unlinkSync(filteredPrdPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            filteredPrdPath = null;
+            if (exitCode !== 0) {
+                console.error(`\nClaude exited with code ${exitCode}`);
+                console.log("Continuing to next iteration...");
+            }
+            // Check for completion signal
+            if (output.includes("<promise>COMPLETE</promise>")) {
+                console.log("\n" + "=".repeat(50));
+                console.log("PRD COMPLETE - All features implemented!");
+                console.log("=".repeat(50));
+                // Send notification if configured
+                if (config.notifyCommand) {
+                    const [cmd, ...cmdArgs] = config.notifyCommand.split(" ");
+                    const notifyProc = spawn(cmd, [...cmdArgs, "Ralph: PRD Complete!"], { stdio: "ignore" });
+                    notifyProc.on("error", () => {
+                        // Notification command not available, ignore
+                    });
+                }
+                break;
+            }
         }
-        // Check for completion signal
-        if (output.includes("<promise>COMPLETE</promise>")) {
-            console.log("\n" + "=".repeat(50));
-            console.log("PRD COMPLETE - All features implemented!");
-            console.log("=".repeat(50));
-            // Try to send notification (optional)
+    }
+    finally {
+        // Clean up temp file if it still exists
+        if (filteredPrdPath) {
             try {
-                spawn("tt", ["notify", "Ralph: PRD Complete!"], { stdio: "ignore" });
+                unlinkSync(filteredPrdPath);
             }
             catch {
-                // tt notify not available, ignore
+                // Ignore cleanup errors
             }
-            break;
         }
     }
     console.log("\nRalph run finished.");

package/dist/utils/config.d.ts

@@ -3,6 +3,7 @@ export interface RalphConfig {
     checkCommand: string;
     testCommand: string;
     imageName?: string;
+    notifyCommand?: string;
 }
 export declare function getRalphDir(): string;
 export declare function loadConfig(): RalphConfig;

package/package.json

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