ralph-cli-sandboxed 0.2.2 → 0.2.3

package/README.md

@@ -20,24 +20,21 @@ ralph init
 ## Quick Start
 
 ```bash
-# 1. Initialize ralph in your project
+# 1. Initialize ralph in your project (creates config AND Docker files)
 ralph init
 
-# 2. Add requirements to your PRD
+# 2. Edit .ralph/prd.json with your requirements, or use:
 ralph add
 
-# 3. Run a single iteration
-ralph once
-
-# 4. Or run until all tasks complete (default)
-ralph run
+# 3. Run in Docker sandbox (auto-builds image on first run)
+ralph docker run
 ```
 
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `ralph init` | Initialize ralph in current project |
+| `ralph init` | Initialize ralph in current project (config + Docker files) |
 | `ralph once` | Run a single automation iteration |
 | `ralph run [n]` | Run automation iterations (default: all tasks) |
 | `ralph add` | Add a new PRD entry (interactive) |
@@ -45,21 +42,45 @@ ralph run
 | `ralph status` | Show PRD completion status |
 | `ralph toggle <n>` | Toggle passes status for entry n |
 | `ralph clean` | Remove all passing entries from PRD |
+| `ralph fix-prd [opts]` | Validate and recover corrupted PRD file |
+| `ralph prompt [opts]` | Display resolved prompt |
 | `ralph docker <sub>` | Manage Docker sandbox environment |
 | `ralph help` | Show help message |
 
 > **Note:** `ralph prd <subcommand>` still works for compatibility (e.g., `ralph prd add`).
 
+### Run Options
+
+```bash
+ralph run --model claude-sonnet-4-20250514  # Use specific model
+ralph run -m claude-sonnet-4-20250514       # Short form
+```
+
+The `--model` flag is passed to the underlying CLI provider. Support depends on your CLI configuration (see [CLI Configuration](#cli-configuration)).
+
+### fix-prd Options
+
+```bash
+ralph fix-prd              # Validate and auto-fix corrupted PRD
+ralph fix-prd --verify     # Check only, don't fix
+ralph fix-prd <backup>     # Restore from specific backup file
+```
+
 ## Configuration
 
 After running `ralph init`, you'll have:
 
 ```
 .ralph/
-├── config.json      # Project configuration
-├── prompt.md        # Shared prompt template
-├── prd.json         # Product requirements document
-└── progress.txt     # Progress tracking file
+├── config.json          # Project configuration
+├── prompt.md            # Shared prompt template
+├── prd.json             # Product requirements document
+├── progress.txt         # Progress tracking file
+├── HOW-TO-WRITE-PRDs.md # PRD writing guide
+└── docker/              # Docker sandbox files
+    ├── Dockerfile
+    ├── docker-compose.yml
+    └── ...
 ```
 
 ### Supported Languages
@@ -80,9 +101,9 @@ Ralph supports multiple AI CLI tools. Select your provider during `ralph init`:
 | [Claude Code](https://github.com/anthropics/claude-code) | Working | `ANTHROPIC_API_KEY` | Default provider. Also supports ~/.claude OAuth credentials |
 | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Working | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | |
 | [OpenCode](https://github.com/anomalyco/opencode) | Working | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY` | Requires [PR #9073](https://github.com/anomalyco/opencode/pull/9073) |
-| [Aider](https://github.com/paul-gauthier/aider) | Untested | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` | |
-| [Codex CLI](https://github.com/openai/codex) | Untested | `OPENAI_API_KEY` | |
-| [AMP](https://ampcode.com/) | Untested | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | |
+| [Aider](https://github.com/paul-gauthier/aider) | Working | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` | |
+| [Codex CLI](https://github.com/openai/codex) | Testers wanted | `OPENAI_API_KEY` | Sponsors welcome |
+| [AMP](https://ampcode.com/) | Testers wanted | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | Sponsors welcome |
 | Custom | - | User-defined | Configure your own CLI |
 
 ### CLI Configuration
@@ -93,15 +114,19 @@ Ralph can be configured to use different AI CLI tools. By default, it uses Claud
 {
   "cli": {
     "command": "claude",
-    "args": ["--permission-mode", "acceptEdits"]
+    "args": ["--permission-mode", "acceptEdits"],
+    "modelArgs": ["--model"],
+    "promptArgs": ["-p"]
   }
 }
 ```
 
 - `command`: The CLI executable name (must be in PATH)
 - `args`: Default arguments passed to the CLI
+- `modelArgs`: Arguments for passing model (e.g., `["--model"]`). Required for `--model` flag support.
+- `promptArgs`: Arguments for passing prompt (e.g., `["-p"]` or `[]` for positional)
 
-The `-p` flag with PRD/prompt content and `--dangerously-skip-permissions` (in containers) are added automatically at runtime.
+The prompt content and `--dangerously-skip-permissions` (in containers) are added automatically at runtime.
 
 ## PRD Format
 
@@ -124,21 +149,42 @@ The PRD (`prd.json`) is an array of requirements:
 
 Categories: `ui`, `feature`, `bugfix`, `setup`, `development`, `testing`, `docs`
 
+### Advanced: File References
+
+PRD steps can include file contents using the `@{filepath}` syntax:
+
+```json
+{
+  "steps": ["Based on content: @{backup.prd.2024-01-15.json}"]
+}
+```
+
+File paths are resolved relative to the project root. Absolute paths are also supported.
+
+## PRD Protection
+
+Ralph includes automatic PRD protection to handle cases where the LLM corrupts the PRD structure:
+
+- **Automatic backup**: Before each run, the PRD is backed up
+- **Validation**: After each iteration, the PRD structure is validated
+- **Smart recovery**: If corrupted, ralph attempts to extract `passes: true` flags from the corrupted PRD and merge them into the backup
+- **Manual recovery**: Use `ralph fix-prd` to validate, auto-fix, or restore from a specific backup
+
+### Dynamic Iteration Limits
+
+To prevent runaway loops, `ralph run` limits iterations to `incomplete_tasks + 3`. This limit adjusts dynamically if new tasks are added during execution.
+
 ## Docker Sandbox
 
 Run ralph in an isolated Docker container:
 
 ```bash
-# Generate Docker files
-ralph docker init
-
-# Build the image
-ralph docker build
-
-# Run container
+# Run container (auto-builds image on first run)
 ralph docker run
 ```
 
+> **Note:** `ralph init` auto-creates Docker files in `.ralph/docker/`. Use `ralph docker init` to regenerate them if needed.
+
 Features:
 - Based on [Claude Code devcontainer](https://github.com/anthropics/claude-code/tree/main/.devcontainer)
 - Network sandboxing (firewall allows only GitHub, npm, Anthropic API)

package/dist/commands/docker.d.ts

@@ -1 +1,6 @@
+/**
+ * Initialize Docker files. Can be called directly from other commands.
+ * @param silent - If true, suppress the "Next steps" message
+ */
+export declare function dockerInit(silent?: boolean): Promise<void>;
 export declare function docker(args: string[]): Promise<void>;

package/dist/commands/docker.js

@@ -345,6 +345,7 @@ function getCliProviderConfig(cliProvider) {
             command: "claude",
             yoloArgs: ["--dangerously-skip-permissions"],
             envVars: ["ANTHROPIC_API_KEY"],
+            modelConfig: { envVar: "CLAUDE_MODEL", note: "Or use --model flag" },
         };
     }
     return {
@@ -352,6 +353,7 @@ function getCliProviderConfig(cliProvider) {
         command: provider.command,
         yoloArgs: provider.yoloArgs || [],
         envVars: provider.envVars || [],
+        modelConfig: provider.modelConfig,
     };
 }
 async function runContainer(ralphDir, imageName, language, javaVersion, cliProvider) {
@@ -397,6 +399,18 @@ async function runContainer(ralphDir, imageName, language, javaVersion, cliProvi
         }
     }
     console.log("");
+    // Display model configuration info if available
+    if (cliConfig.modelConfig) {
+        console.log("Model configuration (optional):");
+        if (cliConfig.modelConfig.envVar) {
+            const note = cliConfig.modelConfig.note ? ` - ${cliConfig.modelConfig.note}` : "";
+            console.log(`  ${cliConfig.modelConfig.envVar}${note}`);
+        }
+        else if (cliConfig.modelConfig.note) {
+            console.log(`  ${cliConfig.modelConfig.note}`);
+        }
+        console.log("");
+    }
     console.log("Set them in docker-compose.yml or export before running.");
     console.log("");
     return new Promise((resolve, reject) => {
@@ -582,6 +596,36 @@ async function cleanImage(imageName, ralphDir) {
     console.log("\nDocker image and associated resources cleaned.");
     console.log("Run 'ralph docker build' to rebuild the image.");
 }
+/**
+ * Initialize Docker files. Can be called directly from other commands.
+ * @param silent - If true, suppress the "Next steps" message
+ */
+export async function dockerInit(silent = false) {
+    const config = loadConfig();
+    const ralphDir = getRalphDir();
+    const imageName = config.imageName ?? `ralph-${basename(process.cwd()).toLowerCase().replace(/[^a-z0-9-]/g, "-")}`;
+    console.log(`\nGenerating Docker files for: ${config.language}`);
+    if ((config.language === "java" || config.language === "kotlin") && config.javaVersion) {
+        console.log(`Java version: ${config.javaVersion}`);
+    }
+    if (config.cliProvider && config.cliProvider !== "claude") {
+        console.log(`CLI provider: ${config.cliProvider}`);
+    }
+    console.log(`Image name: ${imageName}\n`);
+    await generateFiles(ralphDir, config.language, imageName, true, config.javaVersion, config.cliProvider);
+    if (!silent) {
+        console.log(`
+Docker files generated in .ralph/docker/
+
+Next steps:
+  1. Build the image: ralph docker build
+  2. Run container:    ralph docker run
+
+Or use docker compose directly:
+  cd .ralph/docker && docker compose run --rm ralph
+`);
+    }
+}
 export async function docker(args) {
     const subcommand = args[0];
     const subArgs = args.slice(1);

package/dist/commands/fix-prd.d.ts

@@ -0,0 +1 @@
+export declare function fixPrd(args?: string[]): Promise<void>;

package/dist/commands/fix-prd.js

@@ -0,0 +1,201 @@
+import { existsSync, readFileSync, copyFileSync } from "fs";
+import { join, isAbsolute } from "path";
+import { getPaths, getRalphDir } from "../utils/config.js";
+import { validatePrd, attemptRecovery, createBackup, findLatestBackup, createTemplatePrd, readPrdFile, writePrd, } from "../utils/prd-validator.js";
+/**
+ * Resolves a backup path - can be absolute, relative, or just a filename.
+ */
+function resolveBackupPath(backupArg) {
+    if (isAbsolute(backupArg)) {
+        return backupArg;
+    }
+    // Check if it's in the .ralph directory
+    const inRalphDir = join(getRalphDir(), backupArg);
+    if (existsSync(inRalphDir)) {
+        return inRalphDir;
+    }
+    // Otherwise treat as relative to cwd
+    return join(process.cwd(), backupArg);
+}
+/**
+ * Restores PRD from a specific backup file.
+ */
+function restoreFromBackup(prdPath, backupPath) {
+    if (!existsSync(backupPath)) {
+        console.error(`Error: Backup file not found: ${backupPath}`);
+        return false;
+    }
+    try {
+        const backupContent = readFileSync(backupPath, "utf-8");
+        const backupParsed = JSON.parse(backupContent);
+        const validation = validatePrd(backupParsed);
+        if (!validation.valid) {
+            console.error("Error: Backup file contains invalid PRD structure:");
+            validation.errors.slice(0, 3).forEach(err => {
+                console.error(`  - ${err}`);
+            });
+            return false;
+        }
+        // Create backup of current file before overwriting
+        if (existsSync(prdPath)) {
+            const currentBackup = createBackup(prdPath);
+            console.log(`Created backup of current PRD: ${currentBackup}`);
+        }
+        writePrd(prdPath, validation.data);
+        console.log(`\x1b[32m✓ PRD restored from: ${backupPath}\x1b[0m`);
+        console.log(`  Restored ${validation.data.length} entries.`);
+        return true;
+    }
+    catch (err) {
+        console.error(`Error: Failed to read backup file: ${err}`);
+        return false;
+    }
+}
+/**
+ * Handles the case where the PRD file contains invalid JSON.
+ * Attempts to restore from backup or reset to template.
+ */
+function handleBrokenPrd(prdPath) {
+    // Create backup of the broken file (preserving raw content)
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const backupPath = prdPath.replace("prd.json", `backup.prd.${timestamp}.json`);
+    copyFileSync(prdPath, backupPath);
+    console.log(`Created backup of broken file: ${backupPath}\n`);
+    // Try to restore from a previous valid backup
+    const latestBackup = findLatestBackup(prdPath);
+    if (latestBackup && latestBackup !== backupPath) {
+        console.log(`Found previous backup: ${latestBackup}`);
+        try {
+            const backupContent = readFileSync(latestBackup, "utf-8");
+            const backupParsed = JSON.parse(backupContent);
+            const backupValidation = validatePrd(backupParsed);
+            if (backupValidation.valid) {
+                writePrd(prdPath, backupValidation.data);
+                console.log("\x1b[32m✓ PRD restored from backup!\x1b[0m");
+                console.log(`  Restored ${backupValidation.data.length} entries.`);
+                console.log("\x1b[33m  Note: Recent changes may have been lost.\x1b[0m");
+                return;
+            }
+            else {
+                console.log("  Backup is also invalid, cannot restore.\n");
+            }
+        }
+        catch {
+            console.log("  Failed to read backup file.\n");
+        }
+    }
+    else {
+        console.log("  No valid backup found to restore from.\n");
+    }
+    // Reset to template as last resort - with instructions to recover from backup
+    console.log("Resetting PRD to recovery template...");
+    writePrd(prdPath, createTemplatePrd(backupPath));
+    console.log("\x1b[33m✓ PRD reset with recovery task.\x1b[0m");
+    console.log("  Next 'ralph run' will instruct the LLM to recover entries from backup.");
+    console.log(`  Backup location: ${backupPath}`);
+}
+export async function fixPrd(args = []) {
+    // Parse arguments
+    let verifyOnly = false;
+    let backupFile;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--verify" || args[i] === "-v") {
+            verifyOnly = true;
+        }
+        else if (!args[i].startsWith("-")) {
+            backupFile = args[i];
+        }
+    }
+    const paths = getPaths();
+    // If a backup file is specified, restore from it
+    if (backupFile) {
+        const resolvedPath = resolveBackupPath(backupFile);
+        const success = restoreFromBackup(paths.prd, resolvedPath);
+        process.exit(success ? 0 : 1);
+    }
+    if (!existsSync(paths.prd)) {
+        console.error("Error: .ralph/prd.json not found. Run 'ralph init' first.");
+        process.exit(1);
+    }
+    console.log("Checking PRD structure...\n");
+    // Step 1: Try to read and parse the file
+    const parsed = readPrdFile(paths.prd);
+    if (!parsed) {
+        // JSON parsing failed - file is completely broken
+        console.log("\x1b[31m✗ PRD file contains invalid JSON.\x1b[0m\n");
+        if (verifyOnly) {
+            process.exit(1);
+        }
+        handleBrokenPrd(paths.prd);
+        return;
+    }
+    // Step 2: Validate the structure
+    const validation = validatePrd(parsed.content);
+    if (validation.valid) {
+        console.log("\x1b[32m✓ PRD is valid.\x1b[0m");
+        console.log(`  ${validation.data.length} entries found.`);
+        return;
+    }
+    // PRD is invalid
+    console.log("\x1b[31m✗ PRD structure is invalid:\x1b[0m");
+    validation.errors.slice(0, 5).forEach(err => {
+        console.log(`  - ${err}`);
+    });
+    if (validation.errors.length > 5) {
+        console.log(`  - ... and ${validation.errors.length - 5} more errors`);
+    }
+    console.log();
+    if (verifyOnly) {
+        process.exit(1);
+    }
+    // Step 3: Create backup before any modifications
+    const backupPath = createBackup(paths.prd);
+    console.log(`Created backup: ${backupPath}\n`);
+    // Step 4: Attempt recovery strategies
+    console.log("Attempting recovery...\n");
+    // Strategy 1: Try to recover from malformed structure
+    const recovered = attemptRecovery(parsed.content);
+    if (recovered) {
+        // Validate the recovered data
+        const recoveredValidation = validatePrd(recovered);
+        if (recoveredValidation.valid) {
+            writePrd(paths.prd, recovered);
+            console.log("\x1b[32m✓ PRD recovered successfully!\x1b[0m");
+            console.log(`  Recovered ${recovered.length} entries by unwrapping/remapping fields.`);
+            return;
+        }
+    }
+    console.log("  Direct recovery failed.\n");
+    // Strategy 2: Restore from backup
+    const latestBackup = findLatestBackup(paths.prd);
+    if (latestBackup && latestBackup !== backupPath) {
+        console.log(`Found previous backup: ${latestBackup}`);
+        try {
+            const backupContent = readFileSync(latestBackup, "utf-8");
+            const backupParsed = JSON.parse(backupContent);
+            const backupValidation = validatePrd(backupParsed);
+            if (backupValidation.valid) {
+                writePrd(paths.prd, backupValidation.data);
+                console.log("\x1b[32m✓ PRD restored from backup!\x1b[0m");
+                console.log(`  Restored ${backupValidation.data.length} entries.`);
+                console.log("\x1b[33m  Note: Recent changes may have been lost.\x1b[0m");
+                return;
+            }
+            else {
+                console.log("  Backup is also invalid, cannot restore.\n");
+            }
+        }
+        catch {
+            console.log("  Failed to read backup file.\n");
+        }
+    }
+    else {
+        console.log("  No valid backup found to restore from.\n");
+    }
+    // Strategy 3: Reset to recovery template - LLM will fix it on next run
+    console.log("Resetting PRD to recovery template...");
+    writePrd(paths.prd, createTemplatePrd(backupPath));
+    console.log("\x1b[33m✓ PRD reset with recovery task.\x1b[0m");
+    console.log("  Next 'ralph run' will instruct the LLM to recover entries from backup.");
+    console.log(`  Backup location: ${backupPath}`);
+}

package/dist/commands/help.js

@@ -13,6 +13,7 @@ COMMANDS:
   status            Show PRD completion status
   toggle <n>        Toggle passes status for entry n
   clean             Remove all passing entries from the PRD
+  fix-prd [opts]    Validate and recover corrupted PRD file
   prompt [opts]     Display resolved prompt (for testing in Claude Code)
   docker <sub>      Manage Docker sandbox environment
   help              Show this help message
@@ -42,6 +43,10 @@ TOGGLE OPTIONS:
   <n> [n2] [n3]...           Toggle one or more entries by number
   --all, -a                  Toggle all PRD entries
 
+FIX-PRD OPTIONS:
+  <backup-file>              Restore PRD from a specific backup file
+  --verify, -v               Only verify format, don't attempt to fix
+
 DOCKER SUBCOMMANDS:
   docker init       Generate Dockerfile and scripts
   docker build      Build image (always fetches latest Claude Code)
@@ -66,6 +71,9 @@ EXAMPLES:
   ralph toggle 1 2 3         # Toggle multiple entries
   ralph toggle --all         # Toggle all entries
   ralph clean                # Remove passing entries
+  ralph fix-prd              # Validate/recover corrupted PRD file
+  ralph fix-prd --verify     # Check PRD format without fixing
+  ralph fix-prd backup.prd.2024-01-15.json  # Restore from specific backup
   ralph prompt               # Display resolved prompt
   ralph docker init          # Generate Dockerfile for sandboxed env
   ralph docker build         # Build Docker image

package/dist/commands/init.js

@@ -3,6 +3,7 @@ import { join, basename, dirname } from "path";
 import { fileURLToPath } from "url";
 import { getLanguages, generatePromptTemplate, DEFAULT_PRD, DEFAULT_PROGRESS, getCliProviders } from "../templates/prompts.js";
 import { promptSelectWithArrows, promptConfirm, promptInput, promptMultiSelectWithArrows } from "../utils/prompt.js";
+import { dockerInit } from "./docker.js";
 // Get package root directory (works for both dev and installed package)
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -168,11 +169,13 @@ export async function init(_args) {
     else {
         console.log(`Skipped ${RALPH_DIR}/${PRD_GUIDE_FILE} (already exists)`);
     }
+    // Generate Docker files automatically
+    await dockerInit(true);
+    console.log("Created .ralph/docker/ files");
     console.log("\nRalph initialized successfully!");
     console.log("\nNext steps:");
-    console.log("  1. Read .ralph/HOW-TO-WRITE-PRDs.md for guidance on writing PRDs");
-    console.log("  2. Edit .ralph/prd.json to add your project requirements");
-    console.log("  3. Run 'ralph docker init' to generate Docker configuration");
-    console.log("  4. Run 'ralph docker build' to build the container");
-    console.log("  5. Run 'ralph docker run' to start ralph in the container");
+    console.log("  1. Edit .ralph/prd.json to add your project requirements");
+    console.log("  2. Run 'ralph docker run' to start (auto-builds image on first run)");
+    console.log("\nSee .ralph/HOW-TO-WRITE-PRDs.md for guidance on writing PRDs");
+    console.log("To regenerate Docker files: ralph docker init");
 }

package/dist/commands/once.js

@@ -2,7 +2,24 @@ import { spawn } from "child_process";
 import { checkFilesExist, loadConfig, loadPrompt, getPaths, getCliConfig, requireContainer } from "../utils/config.js";
 import { resolvePromptVariables } from "../templates/prompts.js";
 export async function once(args) {
-    const debug = args.includes("--debug") || args.includes("-d");
+    // Parse flags
+    let debug = false;
+    let model;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--debug" || args[i] === "-d") {
+            debug = true;
+        }
+        else if (args[i] === "--model" || args[i] === "-m") {
+            if (i + 1 < args.length) {
+                model = args[i + 1];
+                i++; // Skip the model value
+            }
+            else {
+                console.error("Error: --model requires a value");
+                process.exit(1);
+            }
+        }
+    }
     requireContainer("once");
     checkFilesExist();
     const config = loadConfig();
@@ -16,7 +33,7 @@ export async function once(args) {
     const paths = getPaths();
     const cliConfig = getCliConfig(config);
     console.log("Starting single ralph iteration...\n");
-    // Build CLI arguments: config args + yolo args + prompt args
+    // Build CLI arguments: config args + yolo args + model args + prompt args
     // Use yoloArgs from config if available, otherwise default to Claude's --dangerously-skip-permissions
     const yoloArgs = cliConfig.yoloArgs ?? ["--dangerously-skip-permissions"];
     const promptArgs = cliConfig.promptArgs ?? ["-p"];
@@ -24,9 +41,12 @@ export async function once(args) {
     const cliArgs = [
         ...(cliConfig.args ?? []),
         ...yoloArgs,
-        ...promptArgs,
-        promptValue,
     ];
+    // Add model args if model is specified
+    if (model && cliConfig.modelArgs) {
+        cliArgs.push(...cliConfig.modelArgs, model);
+    }
+    cliArgs.push(...promptArgs, promptValue);
     if (debug) {
         console.log(`[debug] ${cliConfig.command} ${cliArgs.map(a => a.includes(" ") ? `"${a}"` : a).join(" ")}\n`);
     }