ralph-cli-sandboxed 0.2.1 → 0.2.2

package/README.md

@@ -71,6 +71,20 @@ After running `ralph init`, you'll have:
 - **Rust** - `cargo check`, `cargo test`
 - **Custom** - Define your own commands
 
+### Supported CLI Providers
+
+Ralph supports multiple AI CLI tools. Select your provider during `ralph init`:
+
+| CLI | Status | Environment Variables | Notes |
+|-----|--------|----------------------|-------|
+| [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` | |
+| Custom | - | User-defined | Configure your own CLI |
+
 ### CLI Configuration
 
 Ralph can be configured to use different AI CLI tools. By default, it uses Claude Code. Configure in `.ralph/config.json`:
@@ -221,8 +235,8 @@ podman run -v $(pwd):/workspace -v /workspace/node_modules your-image
 ## Requirements
 
 - Node.js 18+
-- [Claude Code CLI](https://github.com/anthropics/claude-code) installed
-- Claude Pro/Max subscription or Anthropic API key
+- A supported AI CLI tool installed (see [Supported CLI Providers](#supported-cli-providers))
+- API key or subscription for your chosen provider
 
 ## License
 

package/dist/commands/once.d.ts

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

package/dist/commands/once.js

@@ -1,7 +1,8 @@
 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) {
+export async function once(args) {
+    const debug = args.includes("--debug") || args.includes("-d");
     requireContainer("once");
     checkFilesExist();
     const config = loadConfig();
@@ -26,6 +27,9 @@ export async function once(_args) {
         ...promptArgs,
         promptValue,
     ];
+    if (debug) {
+        console.log(`[debug] ${cliConfig.command} ${cliArgs.map(a => a.includes(" ") ? `"${a}"` : a).join(" ")}\n`);
+    }
     return new Promise((resolve, reject) => {
         const proc = spawn(cliConfig.command, cliArgs, {
             stdio: "inherit",

package/dist/commands/prd.js

@@ -216,10 +216,10 @@ export function parseListArgs(args) {
                 process.exit(1);
             }
         }
-        else if (args[i] === "--passes") {
+        else if (args[i] === "--passes" || args[i] === "--passed") {
             passesFilter = true;
         }
-        else if (args[i] === "--no-passes") {
+        else if (args[i] === "--no-passes" || args[i] === "--no-passed" || args[i] === "--not-passed" || args[i] === "--not-passes") {
             passesFilter = false;
         }
     }

package/dist/commands/run.js

@@ -25,7 +25,7 @@ function createFilteredPrd(prdPath, category) {
         hasIncomplete: filteredItems.length > 0
     };
 }
-async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig) {
+async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig, debug) {
     return new Promise((resolve, reject) => {
         let output = "";
         // Build CLI arguments: config args + yolo args + prompt args
@@ -43,6 +43,9 @@ async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig
         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"],
         });
@@ -107,6 +110,7 @@ export async function run(args) {
     let category;
     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") {
@@ -126,6 +130,9 @@ export async function run(args) {
         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]);
         }
@@ -176,7 +183,10 @@ 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;
     try {
         for (let i = 1; i <= iterations; i++) {
             console.log(`\n${"=".repeat(50)}`);
@@ -249,7 +259,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);
             // Clean up temp file after each iteration
             try {
                 unlinkSync(filteredPrdPath);
@@ -260,8 +270,27 @@ export async function run(args) {
             filteredPrdPath = null;
             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) {

package/dist/config/cli-providers.json

@@ -61,12 +61,12 @@
       "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"],
+      "envVars": ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
       "credentialMount": null
     },
     "amp": {

package/docs/run-state-machine.md

@@ -0,0 +1,68 @@
+# Run Command State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> ParseFlags : run(args)
+
+    ParseFlags --> DetermineMode
+
+    state DetermineMode {
+        [*] --> CheckLoopFlag
+        CheckLoopFlag --> LoopMode : --loop
+        CheckLoopFlag --> CheckIterationArg : no --loop
+        CheckIterationArg --> CountMode : number provided
+        CheckIterationArg --> AllMode : no number (default)
+    }
+
+    DetermineMode --> CheckItems
+
+    state "Check Items" as CheckItems {
+        [*] --> CreateFilteredPRD
+        CreateFilteredPRD --> HasIncomplete
+        HasIncomplete --> StartIteration : yes
+        HasIncomplete --> HandleComplete : no
+    }
+
+    state HandleComplete {
+        [*] --> CheckMode
+        CheckMode --> WaitForNewItems : LoopMode
+        CheckMode --> PrintComplete : AllMode/CountMode
+        WaitForNewItems --> PollLoop
+        PollLoop --> CheckNewItems : every 30s
+        CheckNewItems --> StartIteration : found
+        CheckNewItems --> PollLoop : not found
+        PrintComplete --> [*]
+    }
+
+    state "Start Iteration" as StartIteration
+
+    StartIteration --> RunCLI
+
+    state "Run CLI" as RunCLI {
+        [*] --> SpawnProcess
+        SpawnProcess --> WaitForExit
+        WaitForExit --> ProcessOutput
+    }
+
+    RunCLI --> CheckResult
+
+    state "Check Result" as CheckResult {
+        [*] --> CheckExitCode
+        CheckExitCode --> TrackFailure : non-zero
+        CheckExitCode --> ResetFailures : zero
+        TrackFailure --> CheckConsecutive
+        CheckConsecutive --> StopRun : >= 3 consecutive
+        CheckConsecutive --> CheckCompletionSignal : < 3
+        ResetFailures --> CheckCompletionSignal
+        CheckCompletionSignal --> HandleLoopComplete : COMPLETE signal
+        CheckCompletionSignal --> NextIteration : no signal
+        HandleLoopComplete --> WaitForNewItems : LoopMode
+        HandleLoopComplete --> PrintFinalStatus : AllMode/CountMode
+        StopRun --> [*]
+        PrintFinalStatus --> [*]
+    }
+
+    NextIteration --> CheckIterationLimit
+    CheckIterationLimit --> CheckItems : more iterations
+    CheckIterationLimit --> [*] : limit reached
+```

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "ralph-cli-sandboxed",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "AI-driven development automation CLI for Claude Code",
   "type": "module",
   "bin": {
-    "ralph": "./dist/index.js"
+    "ralph": "dist/index.js"
   },
   "main": "./dist/index.js",
   "files": [
@@ -13,10 +13,10 @@
     "README.md"
   ],
   "scripts": {
-    "build": "./node_modules/.bin/tsc && npm run copy-config",
+    "build": "tsc && npm run copy-config",
     "copy-config": "mkdir -p dist/config && cp src/config/*.json dist/config/",
     "dev": "npx tsx src/index.ts",
-    "typecheck": "./node_modules/.bin/tsc --noEmit",
+    "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build",
     "prepare": "npm run build"
   },