ralph-cli-sandboxed 0.2.1 → 0.2.3

package/dist/commands/run.js

@@ -1,16 +1,17 @@
 import { spawn } from "child_process";
 import { readFileSync, writeFileSync, unlinkSync } from "fs";
 import { join } from "path";
-import { tmpdir } from "os";
 import { checkFilesExist, loadConfig, loadPrompt, getPaths, getCliConfig, requireContainer } from "../utils/config.js";
 import { resolvePromptVariables } from "../templates/prompts.js";
+import { validatePrd, smartMerge, readPrdFile, writePrd, expandPrdFileReferences } from "../utils/prd-validator.js";
 const CATEGORIES = ["ui", "feature", "bugfix", "setup", "development", "testing", "docs"];
 /**
  * Creates a filtered PRD file containing only incomplete items (passes: false).
  * Optionally filters by category if specified.
+ * Expands @{filepath} references to include file contents.
  * Returns the path to the temp file, or null if all items pass.
  */
-function createFilteredPrd(prdPath, category) {
+function createFilteredPrd(prdPath, baseDir, category) {
     const content = readFileSync(prdPath, "utf-8");
     const items = JSON.parse(content);
     let filteredItems = items.filter(item => item.passes === false);
@@ -18,17 +19,20 @@ function createFilteredPrd(prdPath, category) {
     if (category) {
         filteredItems = filteredItems.filter(item => item.category === category);
     }
-    const tempPath = join(tmpdir(), `ralph-prd-filtered-${Date.now()}.json`);
-    writeFileSync(tempPath, JSON.stringify(filteredItems, null, 2));
+    // Expand @{filepath} references in description and steps
+    const expandedItems = expandPrdFileReferences(filteredItems, baseDir);
+    // Write to .ralph/prd-tasks.json so LLMs see a sensible path
+    const tempPath = join(baseDir, "prd-tasks.json");
+    writeFileSync(tempPath, JSON.stringify(expandedItems, null, 2));
     return {
         tempPath,
         hasIncomplete: filteredItems.length > 0
     };
 }
-async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig) {
+async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig, debug, model) {
     return new Promise((resolve, reject) => {
         let output = "";
-        // Build CLI arguments: config args + yolo args + prompt args
+        // Build CLI arguments: config args + yolo args + model args + prompt args
         const cliArgs = [
             ...(cliConfig.args ?? []),
         ];
@@ -38,11 +42,18 @@ async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig
             const yoloArgs = cliConfig.yoloArgs ?? ["--dangerously-skip-permissions"];
             cliArgs.push(...yoloArgs);
         }
+        // Add model args if model is specified
+        if (model && cliConfig.modelArgs) {
+            cliArgs.push(...cliConfig.modelArgs, model);
+        }
         // Use the filtered PRD (only incomplete items) for the prompt
         // promptArgs specifies flags to use (e.g., ["-p"] for Claude, [] for positional)
         const promptArgs = cliConfig.promptArgs ?? ["-p"];
         const promptValue = `@${filteredPrdPath} @${paths.progress} ${prompt}`;
         cliArgs.push(...promptArgs, promptValue);
+        if (debug) {
+            console.log(`[debug] ${cliConfig.command} ${cliArgs.map(a => a.includes(" ") ? `"${a}"` : a).join(" ")}\n`);
+        }
         const proc = spawn(cliConfig.command, cliArgs, {
             stdio: ["inherit", "pipe", "inherit"],
         });
@@ -102,11 +113,56 @@ function countPrdItems(prdPath, category) {
         incomplete
     };
 }
+/**
+ * Validates the PRD after an iteration and recovers if corrupted.
+ * Uses the validPrd as the source of truth and merges passes flags from the current file.
+ * Returns true if the PRD was corrupted and recovered.
+ */
+function validateAndRecoverPrd(prdPath, validPrd) {
+    const parsed = readPrdFile(prdPath);
+    // If we can't even parse the JSON, restore from valid copy
+    if (!parsed) {
+        console.log("\n\x1b[33mWarning: PRD corrupted (invalid JSON) - restored from memory.\x1b[0m");
+        writePrd(prdPath, validPrd);
+        return { recovered: true, itemsUpdated: 0 };
+    }
+    // Validate the structure
+    const validation = validatePrd(parsed.content);
+    if (validation.valid) {
+        // PRD is valid, no recovery needed
+        return { recovered: false, itemsUpdated: 0 };
+    }
+    // PRD is corrupted - use smart merge to extract passes flags
+    console.log("\n\x1b[33mWarning: PRD format corrupted by LLM - recovering...\x1b[0m");
+    const mergeResult = smartMerge(validPrd, parsed.content);
+    // Write the valid structure back
+    writePrd(prdPath, mergeResult.merged);
+    if (mergeResult.itemsUpdated > 0) {
+        console.log(`\x1b[32mRecovered: merged ${mergeResult.itemsUpdated} passes flag(s) into valid PRD structure.\x1b[0m`);
+    }
+    else {
+        console.log("\x1b[32mRecovered: restored valid PRD structure.\x1b[0m");
+    }
+    if (mergeResult.warnings.length > 0) {
+        mergeResult.warnings.forEach(w => console.log(`  \x1b[33m${w}\x1b[0m`));
+    }
+    return { recovered: true, itemsUpdated: mergeResult.itemsUpdated };
+}
+/**
+ * Loads a valid copy of the PRD to keep in memory.
+ * Returns the validated PRD entries.
+ */
+function loadValidPrd(prdPath) {
+    const content = readFileSync(prdPath, "utf-8");
+    return JSON.parse(content);
+}
 export async function run(args) {
     // Parse flags
     let category;
+    let model;
     let loopMode = false;
     let allModeExplicit = false;
+    let debug = false;
     const filteredArgs = [];
     for (let i = 0; i < args.length; i++) {
         if (args[i] === "--category" || args[i] === "-c") {
@@ -120,12 +176,25 @@ export async function run(args) {
                 process.exit(1);
             }
         }
+        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);
+            }
+        }
         else if (args[i] === "--loop" || args[i] === "-l") {
             loopMode = true;
         }
         else if (args[i] === "--all" || args[i] === "-a") {
             allModeExplicit = true;
         }
+        else if (args[i] === "--debug" || args[i] === "-d") {
+            debug = true;
+        }
         else {
             filteredArgs.push(args[i]);
         }
@@ -142,8 +211,6 @@ export async function run(args) {
     // - Otherwise, default to --all mode (run until all tasks complete)
     const hasIterationArg = filteredArgs.length > 0 && !isNaN(parseInt(filteredArgs[0])) && parseInt(filteredArgs[0]) >= 1;
     const allMode = !loopMode && (allModeExplicit || !hasIterationArg);
-    // In loop mode or all mode, iterations argument is optional (defaults to unlimited)
-    const iterations = (loopMode || allMode) ? (parseInt(filteredArgs[0]) || Infinity) : parseInt(filteredArgs[0]);
     requireContainer("run");
     checkFilesExist();
     const config = loadConfig();
@@ -156,6 +223,10 @@ export async function run(args) {
     });
     const paths = getPaths();
     const cliConfig = getCliConfig(config);
+    // Safety margin for iteration limit (recalculated dynamically each iteration)
+    const ITERATION_SAFETY_MARGIN = 3;
+    // Get requested iteration count (may be adjusted dynamically)
+    const requestedIterations = parseInt(filteredArgs[0]) || Infinity;
     // Container is required, so always run with skip-permissions
     const sandboxed = true;
     if (allMode) {
@@ -167,7 +238,7 @@ export async function run(args) {
         console.log("Starting ralph in loop mode (runs until interrupted)...");
     }
     else {
-        console.log(`Starting ${iterations} ralph iteration(s)...`);
+        console.log(`Starting ralph iterations (requested: ${requestedIterations})...`);
     }
     if (category) {
         console.log(`Filtering PRD items by category: ${category}`);
@@ -176,23 +247,44 @@ export async function run(args) {
     // Track temp file for cleanup
     let filteredPrdPath = null;
     const POLL_INTERVAL_MS = 30000; // 30 seconds between checks when waiting for new items
+    const MAX_CONSECUTIVE_FAILURES = 3; // Stop after this many consecutive failures
     const startTime = Date.now();
+    let consecutiveFailures = 0;
+    let lastExitCode = 0;
+    let iterationCount = 0;
     try {
-        for (let i = 1; i <= iterations; i++) {
+        while (true) {
+            iterationCount++;
+            // Dynamic iteration limit: recalculate based on current incomplete count
+            // This allows the limit to expand if tasks are added during the run
+            const currentCounts = countPrdItems(paths.prd, category);
+            const dynamicMaxIterations = currentCounts.incomplete + ITERATION_SAFETY_MARGIN;
+            // Check if we should stop (not in loop mode)
+            if (!loopMode) {
+                if (allMode && iterationCount > dynamicMaxIterations) {
+                    console.log(`\nStopping: reached iteration limit (${dynamicMaxIterations}) with ${currentCounts.incomplete} tasks remaining.`);
+                    console.log("This may indicate tasks are not completing. Check the PRD and progress.");
+                    break;
+                }
+                if (!allMode && iterationCount > Math.min(requestedIterations, dynamicMaxIterations)) {
+                    break;
+                }
+            }
             console.log(`\n${"=".repeat(50)}`);
             if (allMode) {
-                const counts = countPrdItems(paths.prd, category);
-                console.log(`Iteration ${i} | Progress: ${counts.complete}/${counts.total} complete`);
+                console.log(`Iteration ${iterationCount} | Progress: ${currentCounts.complete}/${currentCounts.total} complete`);
             }
-            else if (loopMode && iterations === Infinity) {
-                console.log(`Iteration ${i}`);
+            else if (loopMode) {
+                console.log(`Iteration ${iterationCount}`);
             }
             else {
-                console.log(`Iteration ${i} of ${iterations}`);
+                console.log(`Iteration ${iterationCount} of ${Math.min(requestedIterations, dynamicMaxIterations)}`);
             }
             console.log(`${"=".repeat(50)}\n`);
+            // Load a valid copy of the PRD before handing to the LLM
+            const validPrd = loadValidPrd(paths.prd);
             // Create a fresh filtered PRD for each iteration (in case items were completed)
-            const { tempPath, hasIncomplete } = createFilteredPrd(paths.prd, category);
+            const { tempPath, hasIncomplete } = createFilteredPrd(paths.prd, paths.dir, category);
             filteredPrdPath = tempPath;
             if (!hasIncomplete) {
                 // Clean up temp file since we're not using it
@@ -217,14 +309,14 @@ export async function run(args) {
                     // Poll for new items
                     while (true) {
                         await sleep(POLL_INTERVAL_MS);
-                        const { hasIncomplete: newItems } = createFilteredPrd(paths.prd, category);
+                        const { hasIncomplete: newItems } = createFilteredPrd(paths.prd, paths.dir, category);
                         if (newItems) {
                             console.log("\nNew incomplete item(s) detected! Resuming...");
                             break;
                         }
                     }
-                    // Decrement i so we don't skip an iteration count
-                    i--;
+                    // Decrement so we don't count waiting as an iteration
+                    iterationCount--;
                     continue;
                 }
                 else {
@@ -249,7 +341,7 @@ export async function run(args) {
                     break;
                 }
             }
-            const { exitCode, output } = await runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig);
+            const { exitCode, output } = await runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig, debug, model);
             // Clean up temp file after each iteration
             try {
                 unlinkSync(filteredPrdPath);
@@ -258,10 +350,31 @@ export async function run(args) {
                 // Ignore cleanup errors
             }
             filteredPrdPath = null;
+            // Validate and recover PRD if the LLM corrupted it
+            validateAndRecoverPrd(paths.prd, validPrd);
             if (exitCode !== 0) {
                 console.error(`\n${cliConfig.command} exited with code ${exitCode}`);
+                // Track consecutive failures to detect persistent errors (e.g., missing API key)
+                if (exitCode === lastExitCode) {
+                    consecutiveFailures++;
+                }
+                else {
+                    consecutiveFailures = 1;
+                    lastExitCode = exitCode;
+                }
+                if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+                    console.error(`\nStopping: ${cliConfig.command} failed ${consecutiveFailures} times in a row with exit code ${exitCode}.`);
+                    console.error("This usually indicates a configuration error (e.g., missing API key).");
+                    console.error("Please check your CLI configuration and try again.");
+                    break;
+                }
                 console.log("Continuing to next iteration...");
             }
+            else {
+                // Reset failure tracking on success
+                consecutiveFailures = 0;
+                lastExitCode = 0;
+            }
             // Check for completion signal
             if (output.includes("<promise>COMPLETE</promise>")) {
                 if (loopMode) {
@@ -273,7 +386,7 @@ export async function run(args) {
                     // Poll for new items
                     while (true) {
                         await sleep(POLL_INTERVAL_MS);
-                        const { hasIncomplete: newItems } = createFilteredPrd(paths.prd, category);
+                        const { hasIncomplete: newItems } = createFilteredPrd(paths.prd, paths.dir, category);
                         if (newItems) {
                             console.log("\nNew incomplete item(s) detected! Resuming...");
                             break;

package/dist/config/cli-providers.json

@@ -11,7 +11,12 @@
         "install": "# Install Claude Code CLI (as node user so it installs to /home/node/.local/bin)\nRUN su - node -c 'curl -fsSL https://claude.ai/install.sh | bash' \\\n    && echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> /home/node/.zshrc"
       },
       "envVars": ["ANTHROPIC_API_KEY"],
-      "credentialMount": "~/.claude:/home/node/.claude"
+      "credentialMount": "~/.claude:/home/node/.claude",
+      "modelConfig": {
+        "envVar": "CLAUDE_MODEL",
+        "note": "Or use: ralph run --model <model>"
+      },
+      "modelArgs": ["--model"]
     },
     "aider": {
       "name": "Aider",
@@ -25,7 +30,12 @@
         "note": "Check 'aider --help' for available flags"
       },
       "envVars": ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
-      "credentialMount": null
+      "credentialMount": null,
+      "modelConfig": {
+        "envVar": "AIDER_MODEL",
+        "note": "Or use: ralph run --model <model>"
+      },
+      "modelArgs": ["--model"]
     },
     "codex": {
       "name": "OpenAI Codex CLI",
@@ -39,7 +49,12 @@
         "note": "Check 'codex --help' for available flags"
       },
       "envVars": ["OPENAI_API_KEY"],
-      "credentialMount": null
+      "credentialMount": null,
+      "modelConfig": {
+        "envVar": "CODEX_MODEL",
+        "note": "Or use: ralph run --model <model>"
+      },
+      "modelArgs": ["--model"]
     },
     "gemini": {
       "name": "Gemini CLI",
@@ -53,7 +68,12 @@
         "note": "Check 'gemini --help' for available flags"
       },
       "envVars": ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
-      "credentialMount": "~/.gemini:/home/node/.gemini"
+      "credentialMount": "~/.gemini:/home/node/.gemini",
+      "modelConfig": {
+        "envVar": "GEMINI_MODEL",
+        "note": "Or use: ralph run --model <model>"
+      },
+      "modelArgs": ["--model"]
     },
     "opencode": {
       "name": "OpenCode",
@@ -61,13 +81,17 @@
       "command": "opencode",
       "defaultArgs": [],
       "yoloArgs": ["--yolo"],
-      "promptArgs": [],
+      "promptArgs": ["run"],
       "docker": {
         "install": "# Install OpenCode (as node user)\nRUN su - node -c 'curl -fsSL https://opencode.ai/install | bash' \\\n    && echo 'export PATH=\"$HOME/.opencode/bin:$PATH\"' >> /home/node/.zshrc",
         "note": "Check 'opencode --help' for available flags"
       },
-      "envVars": ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GOOGLE_API_KEY"],
-      "credentialMount": null
+      "envVars": ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
+      "credentialMount": null,
+      "modelConfig": {
+        "note": "Or use: ralph run --model <model>"
+      },
+      "modelArgs": ["--model"]
     },
     "amp": {
       "name": "AMP CLI",
@@ -81,7 +105,11 @@
         "note": "Check 'amp --help' for available flags"
       },
       "envVars": ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
-      "credentialMount": null
+      "credentialMount": null,
+      "modelConfig": {
+        "note": "Or use: ralph run --model <model>"
+      },
+      "modelArgs": ["--model"]
     },
     "custom": {
       "name": "Custom CLI",

package/dist/index.js

@@ -9,6 +9,7 @@ import { run } from "./commands/run.js";
 import { prd, prdAdd, prdList, prdStatus, prdToggle, prdClean, parseListArgs } from "./commands/prd.js";
 import { docker } from "./commands/docker.js";
 import { prompt } from "./commands/prompt.js";
+import { fixPrd } from "./commands/fix-prd.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 function getPackageInfo() {
@@ -24,6 +25,7 @@ const commands = {
     prd,
     prompt,
     docker,
+    "fix-prd": (args) => fixPrd(args),
     // Top-level PRD commands (shortcuts)
     add: () => prdAdd(),
     list: (args) => {

package/dist/templates/prompts.d.ts

@@ -34,11 +34,16 @@ export interface CliProviderConfig {
     defaultArgs: string[];
     yoloArgs: string[];
     promptArgs: string[];
+    modelArgs?: string[];
     docker: {
         install: string;
     };
     envVars: string[];
     credentialMount: string | null;
+    modelConfig?: {
+        envVar?: string;
+        note?: string;
+    };
 }
 interface CliProvidersJson {
     providers: Record<string, CliProviderConfig>;

package/dist/templates/prompts.js

@@ -81,13 +81,13 @@ TECHNOLOGY STACK:
 - Technologies: $technologies
 
 INSTRUCTIONS:
-1. Read the @.ralph/prd.json file to find the highest priority feature that has "passes": false
+1. Read the provided PRD tasks file to find the first incomplete feature
 2. Implement that feature completely
 3. Verify your changes work by running:
    - Type/build check: $checkCommand
    - Tests: $testCommand
-4. Update the PRD entry to set "passes": true once verified
-5. Append a brief note about what you did to @.ralph/progress.txt
+4. Update .ralph/prd.json to set "passes": true for the completed feature
+5. Append a brief note about what you did to .ralph/progress.txt
 6. Create a git commit with a descriptive message for this feature
 7. Only work on ONE feature per execution
 

package/dist/utils/config.d.ts

@@ -3,6 +3,7 @@ export interface CliConfig {
     args?: string[];
     yoloArgs?: string[];
     promptArgs?: string[];
+    modelArgs?: string[];
 }
 export interface RalphConfig {
     language: string;

package/dist/utils/config.js

@@ -1,32 +1,34 @@
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
+import { getCliProviders } from "../templates/prompts.js";
 export const DEFAULT_CLI_CONFIG = {
     command: "claude",
     args: ["--permission-mode", "acceptEdits"],
     promptArgs: ["-p"],
 };
-// Lazy import to avoid circular dependency
-let _getCliProviders = null;
 export function getCliConfig(config) {
     const cliConfig = config.cli ?? DEFAULT_CLI_CONFIG;
-    // If promptArgs is already set, use it
-    if (cliConfig.promptArgs !== undefined) {
-        return cliConfig;
-    }
-    // Look up promptArgs from cliProvider if available
+    // Look up promptArgs and modelArgs from cliProvider if available
     if (config.cliProvider) {
-        if (!_getCliProviders) {
-            // Dynamic import to avoid circular dependency
-            _getCliProviders = require("../templates/prompts.js").getCliProviders;
-        }
-        const providers = _getCliProviders();
+        const providers = getCliProviders();
         const provider = providers[config.cliProvider];
-        if (provider?.promptArgs !== undefined) {
-            return { ...cliConfig, promptArgs: provider.promptArgs };
+        const result = { ...cliConfig };
+        // Use provider's promptArgs if not already set
+        if (result.promptArgs === undefined && provider?.promptArgs !== undefined) {
+            result.promptArgs = provider.promptArgs;
+        }
+        // Use provider's modelArgs if not already set
+        if (result.modelArgs === undefined && provider?.modelArgs !== undefined) {
+            result.modelArgs = provider.modelArgs;
+        }
+        // Default promptArgs for backwards compatibility
+        if (result.promptArgs === undefined) {
+            result.promptArgs = ["-p"];
         }
+        return result;
     }
     // Default to -p for backwards compatibility
-    return { ...cliConfig, promptArgs: ["-p"] };
+    return { ...cliConfig, promptArgs: cliConfig.promptArgs ?? ["-p"] };
 }
 const RALPH_DIR = ".ralph";
 const CONFIG_FILE = "config.json";

package/dist/utils/prd-validator.d.ts

@@ -0,0 +1,80 @@
+export interface PrdEntry {
+    category: string;
+    description: string;
+    steps: string[];
+    passes: boolean;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    data?: PrdEntry[];
+}
+export interface MergeResult {
+    merged: PrdEntry[];
+    itemsUpdated: number;
+    warnings: string[];
+}
+interface ExtractedItem {
+    description: string;
+    passes: boolean;
+}
+/**
+ * Validates that a PRD structure is correct.
+ * Returns validation result with parsed data if valid.
+ */
+export declare function validatePrd(content: unknown): ValidationResult;
+/**
+ * Extracts items marked as passing from a corrupted PRD structure.
+ * Handles various malformed structures LLMs might create.
+ */
+export declare function extractPassingItems(corrupted: unknown): ExtractedItem[];
+/**
+ * Smart merge: applies passes flags from corrupted PRD to valid original.
+ * Only updates items that were marked as passing in the corrupted version.
+ */
+export declare function smartMerge(original: PrdEntry[], corrupted: unknown): MergeResult;
+/**
+ * Attempts to recover a valid PRD from corrupted content.
+ * Returns the recovered PRD entries or null if recovery failed.
+ */
+export declare function attemptRecovery(corrupted: unknown): PrdEntry[] | null;
+/**
+ * Creates a timestamped backup of the PRD file.
+ * Returns the backup path.
+ */
+export declare function createBackup(prdPath: string): string;
+/**
+ * Finds the most recent backup file.
+ * Returns the path or null if no backups exist.
+ */
+export declare function findLatestBackup(prdPath: string): string | null;
+/**
+ * Creates a PRD template with a recovery entry that instructs the LLM to fix the PRD.
+ * Uses @{filepath} syntax to include backup content when expanded.
+ * @param backupPath - Absolute path to the backup file containing the corrupted PRD
+ */
+export declare function createTemplatePrd(backupPath?: string): PrdEntry[];
+/**
+ * Reads and parses a PRD file, handling potential JSON errors.
+ * Returns the parsed content or null if it couldn't be parsed.
+ */
+export declare function readPrdFile(prdPath: string): {
+    content: unknown;
+    raw: string;
+} | null;
+/**
+ * Writes a PRD to file.
+ */
+export declare function writePrd(prdPath: string, entries: PrdEntry[]): void;
+/**
+ * Expands @{filepath} patterns in a string with actual file contents.
+ * Similar to curl's @ syntax for including file contents.
+ * Paths are resolved relative to the .ralph directory.
+ */
+export declare function expandFileReferences(text: string, baseDir: string): string;
+/**
+ * Expands file references in all string fields of PRD entries.
+ * Returns a new array with expanded content.
+ */
+export declare function expandPrdFileReferences(entries: PrdEntry[], baseDir: string): PrdEntry[];
+export {};