ralph-cli-sandboxed 0.2.2 → 0.2.4

package/dist/commands/run.js

@@ -1,16 +1,17 @@
 import { spawn } from "child_process";
-import { readFileSync, writeFileSync, unlinkSync } from "fs";
+import { existsSync, 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,62 @@ 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, debug) {
+/**
+ * Syncs passes flags from prd-tasks.json back to prd.json.
+ * If the LLM marked any item as passes: true in prd-tasks.json,
+ * find the matching item in prd.json and update it.
+ * Returns the number of items synced.
+ */
+function syncPassesFromTasks(tasksPath, prdPath) {
+    // Check if tasks file exists
+    if (!existsSync(tasksPath)) {
+        return 0;
+    }
+    try {
+        const tasksContent = readFileSync(tasksPath, "utf-8");
+        const tasks = JSON.parse(tasksContent);
+        const prdContent = readFileSync(prdPath, "utf-8");
+        const prd = JSON.parse(prdContent);
+        let synced = 0;
+        // Find tasks that were marked as passing
+        for (const task of tasks) {
+            if (task.passes === true) {
+                // Find matching item in prd by description
+                const match = prd.find(item => item.description === task.description ||
+                    item.description.includes(task.description) ||
+                    task.description.includes(item.description));
+                if (match && !match.passes) {
+                    match.passes = true;
+                    synced++;
+                }
+            }
+        }
+        // Write back if any items were synced
+        if (synced > 0) {
+            writeFileSync(prdPath, JSON.stringify(prd, null, 2) + "\n");
+            console.log(`\x1b[32mSynced ${synced} completed item(s) from prd-tasks.json to prd.json\x1b[0m`);
+        }
+        return synced;
+    }
+    catch {
+        // Ignore errors - the validation step will handle any issues
+        return 0;
+    }
+}
+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,6 +84,10 @@ 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"];
@@ -105,9 +155,53 @@ 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;
@@ -124,6 +218,16 @@ 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;
         }
@@ -149,8 +253,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();
@@ -163,6 +265,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) {
@@ -174,7 +280,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}`);
@@ -187,22 +293,40 @@ export async function run(args) {
     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
@@ -227,14 +351,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 {
@@ -259,7 +383,10 @@ export async function run(args) {
                     break;
                 }
             }
-            const { exitCode, output } = await runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig, debug);
+            const { exitCode, output } = await runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig, debug, model);
+            // Sync any completed items from prd-tasks.json back to prd.json
+            // This catches cases where the LLM updated prd-tasks.json instead of prd.json
+            syncPassesFromTasks(filteredPrdPath, paths.prd);
             // Clean up temp file after each iteration
             try {
                 unlinkSync(filteredPrdPath);
@@ -268,6 +395,8 @@ 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)
@@ -302,7 +431,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",
@@ -67,21 +87,29 @@
         "note": "Check 'opencode --help' for available flags"
       },
       "envVars": ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
-      "credentialMount": null
+      "credentialMount": null,
+      "modelConfig": {
+        "note": "Or use: ralph run --model <model>"
+      },
+      "modelArgs": ["--model"]
     },
     "amp": {
       "name": "AMP CLI",
       "description": "Sourcegraph's AMP coding agent",
       "command": "amp",
       "defaultArgs": [],
-      "yoloArgs": ["--yolo"],
-      "promptArgs": [],
+      "yoloArgs": ["--dangerously-allow-all"],
+      "promptArgs": ["-x"],
       "docker": {
         "install": "# Install AMP CLI (as node user)\nRUN su - node -c 'curl -fsSL https://ampcode.com/install.sh | bash' \\\n    && echo 'export PATH=\"$HOME/.amp/bin:$PATH\"' >> /home/node/.zshrc",
         "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 {};