bmalph 2.2.0 → 2.3.0

package/dist/utils/github.js

@@ -4,11 +4,6 @@ const BMAD_REPO = {
     repo: "BMAD-METHOD",
     branch: "main",
 };
-const RALPH_REPO = {
-    owner: "snarktank",
-    repo: "ralph",
-    branch: "main",
-};
 const DEFAULT_TIMEOUT_MS = 10000;
 const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const DEFAULT_MAX_CACHE_SIZE = 100;
@@ -182,27 +177,15 @@ export class GitHubClient {
     async checkUpstream(bundled) {
         const errors = [];
         let bmadStatus = null;
-        let ralphStatus = null;
-        // Fetch both in parallel
-        const [bmadResult, ralphResult] = await Promise.all([
-            this.fetchLatestCommit(BMAD_REPO),
-            this.fetchLatestCommit(RALPH_REPO),
-        ]);
+        const bmadResult = await this.fetchLatestCommit(BMAD_REPO);
         if (bmadResult.success) {
             bmadStatus = buildUpstreamStatus(BMAD_REPO, bundled.bmadCommit, bmadResult.data.shortSha);
         }
         else {
             errors.push({ ...bmadResult.error, repo: "bmad" });
         }
-        if (ralphResult.success) {
-            ralphStatus = buildUpstreamStatus(RALPH_REPO, bundled.ralphCommit, ralphResult.data.shortSha);
-        }
-        else {
-            errors.push({ ...ralphResult.error, repo: "ralph" });
-        }
         return {
             bmad: bmadStatus,
-            ralph: ralphStatus,
             errors,
         };
     }

package/dist/utils/json.js

@@ -1,5 +1,5 @@
 import { readFile } from "fs/promises";
-import { isEnoent, formatError } from "./errors.js";
+import { isEnoent } from "./errors.js";
 /**
  * Reads and parses a JSON file with proper error discrimination:
  * - File not found → returns null
@@ -21,6 +21,6 @@ export async function readJsonFile(path) {
         return JSON.parse(content);
     }
     catch (err) {
-        throw new Error(`Invalid JSON in ${path}: ${formatError(err)}`);
+        throw new Error(`Invalid JSON in ${path}`, { cause: err });
     }
 }

package/dist/utils/state.js

@@ -1,7 +1,7 @@
 import { mkdir } from "fs/promises";
 import { join } from "path";
 import { readJsonFile } from "./json.js";
-import { validateState, validateRalphLoopStatus } from "./validate.js";
+import { validateState, validateRalphLoopStatus, normalizeRalphStatus } from "./validate.js";
 import { STATE_DIR, RALPH_STATUS_FILE } from "./constants.js";
 import { atomicWriteFile } from "./file-system.js";
 import { warn } from "./logger.js";
@@ -186,6 +186,12 @@ export async function readRalphStatus(projectDir) {
     try {
         return validateRalphLoopStatus(data);
     }
+    catch {
+        // camelCase validation failed — try bash snake_case format
+    }
+    try {
+        return normalizeRalphStatus(data);
+    }
     catch (err) {
         warn(`Ralph status file is corrupted, using defaults: ${formatError(err)}`);
         return DEFAULT_RALPH_STATUS;

package/dist/utils/validate.d.ts

@@ -27,6 +27,7 @@ export interface RalphLoopStatus {
     tasksTotal: number;
 }
 export declare function validateRalphLoopStatus(data: unknown): RalphLoopStatus;
+export declare function normalizeRalphStatus(data: unknown): RalphLoopStatus;
 /**
  * Validates a project name for filesystem safety.
  * Checks for:

package/dist/utils/validate.js

@@ -1,4 +1,12 @@
 import { MAX_PROJECT_NAME_LENGTH } from "./constants.js";
+const VALID_PLATFORM_IDS = [
+    "claude-code",
+    "codex",
+    "cursor",
+    "windsurf",
+    "copilot",
+    "aider",
+];
 const VALID_STATUSES = ["planning", "implementing", "completed"];
 // Invalid filesystem characters (Windows + POSIX)
 const INVALID_FS_CHARS = /[<>:"/\\|?*]/;
@@ -37,12 +45,8 @@ function validateUpstreamVersions(data) {
     if (typeof data.bmadCommit !== "string") {
         throw new Error("upstreamVersions.bmadCommit must be a string");
     }
-    if (typeof data.ralphCommit !== "string") {
-        throw new Error("upstreamVersions.ralphCommit must be a string");
-    }
     return {
         bmadCommit: data.bmadCommit,
-        ralphCommit: data.ralphCommit,
     };
 }
 export function validateConfig(data) {
@@ -54,6 +58,13 @@ export function validateConfig(data) {
         throw new Error("config.createdAt must be a string");
     }
     const description = typeof data.description === "string" ? data.description : "";
+    let platform;
+    if (data.platform !== undefined) {
+        if (typeof data.platform !== "string" || !VALID_PLATFORM_IDS.includes(data.platform)) {
+            throw new Error(`config.platform must be one of: ${VALID_PLATFORM_IDS.join(", ")}`);
+        }
+        platform = data.platform;
+    }
     const upstreamVersions = data.upstreamVersions !== undefined
         ? validateUpstreamVersions(data.upstreamVersions)
         : undefined;
@@ -61,6 +72,7 @@ export function validateConfig(data) {
         name: data.name,
         description,
         createdAt: data.createdAt,
+        ...(platform !== undefined && { platform }),
         upstreamVersions,
     };
 }
@@ -158,6 +170,25 @@ export function validateRalphLoopStatus(data) {
         tasksTotal: data.tasksTotal,
     };
 }
+const BASH_STATUS_MAP = {
+    running: "running",
+    halted: "blocked",
+    stopped: "blocked",
+    completed: "completed",
+    success: "completed",
+};
+export function normalizeRalphStatus(data) {
+    assertObject(data, "normalizeRalphStatus");
+    const loopCount = typeof data.loop_count === "number" ? data.loop_count : 0;
+    const rawStatus = typeof data.status === "string" ? data.status : undefined;
+    const status = (rawStatus !== undefined ? BASH_STATUS_MAP[rawStatus] : undefined) ?? "running";
+    return {
+        loopCount,
+        status,
+        tasksCompleted: 0,
+        tasksTotal: 0,
+    };
+}
 /**
  * Validates a project name for filesystem safety.
  * Checks for:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmalph",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Unified AI Development Framework - BMAD phases with Ralph execution loop for Claude Code",
   "type": "module",
   "bin": {
@@ -63,13 +63,13 @@
     "inquirer": "^13.2.1"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
+    "@eslint/js": "^10.0.1",
     "@types/node": "^20.0.0",
     "@vitest/coverage-v8": "^4.0.18",
-    "eslint": "^9.39.2",
+    "eslint": "^10.0.1",
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.53.1",
+    "typescript-eslint": "^8.56.0",
     "vitest": "^4.0.18"
   }
 }

package/ralph/drivers/claude-code.sh

@@ -0,0 +1,118 @@
+#!/bin/bash
+# Claude Code driver for Ralph
+# Provides platform-specific CLI invocation logic
+
+# Driver identification
+driver_name() {
+    echo "claude-code"
+}
+
+driver_display_name() {
+    echo "Claude Code"
+}
+
+driver_cli_binary() {
+    echo "claude"
+}
+
+driver_min_version() {
+    echo "2.0.76"
+}
+
+# Check if the CLI binary is available
+driver_check_available() {
+    command -v "$(driver_cli_binary)" &>/dev/null
+}
+
+# Valid tool patterns for --allowedTools validation
+# Sets the global VALID_TOOL_PATTERNS array
+driver_valid_tools() {
+    VALID_TOOL_PATTERNS=(
+        "Write"
+        "Read"
+        "Edit"
+        "MultiEdit"
+        "Glob"
+        "Grep"
+        "Task"
+        "TodoWrite"
+        "WebFetch"
+        "WebSearch"
+        "Bash"
+        "Bash(git *)"
+        "Bash(npm *)"
+        "Bash(bats *)"
+        "Bash(python *)"
+        "Bash(node *)"
+        "NotebookEdit"
+    )
+}
+
+# Build the CLI command arguments
+# Populates global CLAUDE_CMD_ARGS array
+# Parameters:
+#   $1 - prompt_file: path to the prompt file
+#   $2 - loop_context: context string for session continuity
+#   $3 - session_id: session ID for resume (empty for new session)
+driver_build_command() {
+    local prompt_file=$1
+    local loop_context=$2
+    local session_id=$3
+
+    # Note: We do NOT use --dangerously-skip-permissions here. Tool permissions
+    # are controlled via --allowedTools from CLAUDE_ALLOWED_TOOLS in .ralphrc.
+    # This preserves the permission denial circuit breaker (Issue #101).
+    CLAUDE_CMD_ARGS=("$(driver_cli_binary)")
+
+    if [[ ! -f "$prompt_file" ]]; then
+        echo "ERROR: Prompt file not found: $prompt_file" >&2
+        return 1
+    fi
+
+    # Output format
+    if [[ "$CLAUDE_OUTPUT_FORMAT" == "json" ]]; then
+        CLAUDE_CMD_ARGS+=("--output-format" "json")
+    fi
+
+    # Allowed tools
+    if [[ -n "$CLAUDE_ALLOWED_TOOLS" ]]; then
+        CLAUDE_CMD_ARGS+=("--allowedTools")
+        local IFS=','
+        read -ra tools_array <<< "$CLAUDE_ALLOWED_TOOLS"
+        for tool in "${tools_array[@]}"; do
+            tool=$(echo "$tool" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+            if [[ -n "$tool" ]]; then
+                CLAUDE_CMD_ARGS+=("$tool")
+            fi
+        done
+    fi
+
+    # Session resume
+    # IMPORTANT: Use --resume with explicit session ID instead of --continue.
+    # --continue resumes the "most recent session in current directory" which
+    # can hijack active Claude Code sessions. --resume with a specific session ID
+    # ensures we only resume Ralph's own sessions. (Issue #151)
+    if [[ "$CLAUDE_USE_CONTINUE" == "true" && -n "$session_id" ]]; then
+        CLAUDE_CMD_ARGS+=("--resume" "$session_id")
+    fi
+
+    # Loop context as system prompt
+    if [[ -n "$loop_context" ]]; then
+        CLAUDE_CMD_ARGS+=("--append-system-prompt" "$loop_context")
+    fi
+
+    # Prompt content
+    local prompt_content
+    prompt_content=$(cat "$prompt_file")
+    CLAUDE_CMD_ARGS+=("-p" "$prompt_content")
+}
+
+# Whether this driver supports session continuity
+driver_supports_sessions() {
+    return 0  # true
+}
+
+# Stream filter for live output (jq filter for JSON streaming)
+driver_stream_filter() {
+    echo '.content // empty | select(type == "string")'
+}

package/ralph/drivers/codex.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# OpenAI Codex driver for Ralph
+# Provides platform-specific CLI invocation logic for Codex
+
+driver_name() {
+    echo "codex"
+}
+
+driver_display_name() {
+    echo "OpenAI Codex"
+}
+
+driver_cli_binary() {
+    echo "codex"
+}
+
+driver_min_version() {
+    echo "0.1.0"
+}
+
+driver_check_available() {
+    command -v "$(driver_cli_binary)" &>/dev/null
+}
+
+# Codex tool names differ from Claude Code
+driver_valid_tools() {
+    VALID_TOOL_PATTERNS=(
+        "shell"
+        "read_file"
+        "write_file"
+        "edit_file"
+        "list_directory"
+        "search_files"
+    )
+}
+
+# Build Codex CLI command
+# Codex uses: codex exec [--resume <id>] --json "prompt"
+driver_build_command() {
+    local prompt_file=$1
+    local loop_context=$2
+    local session_id=$3
+
+    CLAUDE_CMD_ARGS=("$(driver_cli_binary)" "exec")
+
+    if [[ ! -f "$prompt_file" ]]; then
+        echo "ERROR: Prompt file not found: $prompt_file" >&2
+        return 1
+    fi
+
+    # JSON output
+    CLAUDE_CMD_ARGS+=("--json")
+
+    # Sandbox mode - workspace write access
+    CLAUDE_CMD_ARGS+=("--sandbox" "workspace-write")
+
+    # Session resume — gated on CLAUDE_USE_CONTINUE to respect --no-continue flag
+    if [[ "$CLAUDE_USE_CONTINUE" == "true" && -n "$session_id" ]]; then
+        CLAUDE_CMD_ARGS+=("--resume" "$session_id")
+    fi
+
+    # Build prompt with context
+    local prompt_content
+    prompt_content=$(cat "$prompt_file")
+    if [[ -n "$loop_context" ]]; then
+        prompt_content="$loop_context
+
+$prompt_content"
+    fi
+
+    CLAUDE_CMD_ARGS+=("$prompt_content")
+}
+
+driver_supports_sessions() {
+    return 0  # true - Codex supports session resume
+}
+
+# Codex outputs JSONL events
+driver_stream_filter() {
+    echo 'select(.type == "message") | .content // empty'
+}

package/ralph/ralph_import.sh

@@ -7,6 +7,17 @@ set -e
 # Configuration
 CLAUDE_CODE_CMD="claude"
 
+# Platform driver support
+SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"
+PLATFORM_DRIVER="${PLATFORM_DRIVER:-claude-code}"
+
+# Source platform driver if available
+if [[ -f "$SCRIPT_DIR/drivers/${PLATFORM_DRIVER}.sh" ]]; then
+    # shellcheck source=/dev/null
+    source "$SCRIPT_DIR/drivers/${PLATFORM_DRIVER}.sh"
+    CLAUDE_CODE_CMD="$(driver_cli_binary)"
+fi
+
 # Modern CLI Configuration (Phase 1.1)
 # These flags enable structured JSON output and controlled file operations
 CLAUDE_OUTPUT_FORMAT="json"

package/ralph/ralph_loop.sh

@@ -66,7 +66,8 @@ RALPH_SESSION_HISTORY_FILE="$RALPH_DIR/.ralph_session_history"  # Session transi
 CLAUDE_SESSION_EXPIRY_HOURS=${CLAUDE_SESSION_EXPIRY_HOURS:-24}
 
 # Valid tool patterns for --allowed-tools validation
-# Tools can be exact matches or pattern matches with wildcards in parentheses
+# Default: Claude Code tools. Platform driver overwrites via driver_valid_tools() in main().
+# Validation runs in main() after load_platform_driver so the correct patterns are in effect.
 VALID_TOOL_PATTERNS=(
     "Write"
     "Read"
@@ -98,6 +99,9 @@ TEST_PERCENTAGE_THRESHOLD=30  # If more than 30% of recent loops are test-only,
 RALPHRC_FILE=".ralphrc"
 RALPHRC_LOADED=false
 
+# Platform driver (set from .ralphrc or environment)
+PLATFORM_DRIVER="${PLATFORM_DRIVER:-claude-code}"
+
 # load_ralphrc - Load project-specific configuration from .ralphrc
 #
 # This function sources .ralphrc if it exists, applying project-specific
@@ -155,6 +159,26 @@ load_ralphrc() {
     return 0
 }
 
+# Source platform driver
+load_platform_driver() {
+    local driver_file="$SCRIPT_DIR/drivers/${PLATFORM_DRIVER}.sh"
+    if [[ ! -f "$driver_file" ]]; then
+        log_status "ERROR" "Platform driver not found: $driver_file"
+        log_status "ERROR" "Available drivers: $(ls "$SCRIPT_DIR/drivers/"*.sh 2>/dev/null | xargs -n1 basename | sed 's/.sh$//' | tr '\n' ' ')"
+        exit 1
+    fi
+    # shellcheck source=/dev/null
+    source "$driver_file"
+
+    # Initialize driver-specific tool patterns
+    driver_valid_tools
+
+    # Set CLI binary from driver
+    CLAUDE_CODE_CMD="$(driver_cli_binary)"
+
+    log_status "INFO" "Platform driver: $(driver_display_name) ($(driver_cli_binary))"
+}
+
 # Colors for terminal output
 RED='\033[0;31m'
 GREEN='\033[0;32m'
@@ -949,68 +973,11 @@ update_session_last_used() {
 # Global array for Claude command arguments (avoids shell injection)
 declare -a CLAUDE_CMD_ARGS=()
 
-# Build Claude CLI command with modern flags using array (shell-injection safe)
+# Build CLI command with platform driver (shell-injection safe)
+# Delegates to the active platform driver's driver_build_command()
 # Populates global CLAUDE_CMD_ARGS array for direct execution
-# Uses -p flag with prompt content (Claude CLI does not have --prompt-file)
 build_claude_command() {
-    local prompt_file=$1
-    local loop_context=$2
-    local session_id=$3
-
-    # Reset global array
-    # Note: We do NOT use --dangerously-skip-permissions here. Tool permissions
-    # are controlled via --allowedTools from CLAUDE_ALLOWED_TOOLS in .ralphrc.
-    # This preserves the permission denial circuit breaker (Issue #101).
-    CLAUDE_CMD_ARGS=("$CLAUDE_CODE_CMD")
-
-    # Check if prompt file exists
-    if [[ ! -f "$prompt_file" ]]; then
-        log_status "ERROR" "Prompt file not found: $prompt_file"
-        return 1
-    fi
-
-    # Add output format flag
-    if [[ "$CLAUDE_OUTPUT_FORMAT" == "json" ]]; then
-        CLAUDE_CMD_ARGS+=("--output-format" "json")
-    fi
-
-    # Add allowed tools (each tool as separate array element)
-    if [[ -n "$CLAUDE_ALLOWED_TOOLS" ]]; then
-        CLAUDE_CMD_ARGS+=("--allowedTools")
-        # Split by comma and add each tool
-        local IFS=','
-        read -ra tools_array <<< "$CLAUDE_ALLOWED_TOOLS"
-        for tool in "${tools_array[@]}"; do
-            # Trim whitespace
-            tool=$(echo "$tool" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
-            if [[ -n "$tool" ]]; then
-                CLAUDE_CMD_ARGS+=("$tool")
-            fi
-        done
-    fi
-
-    # Add session continuity flag
-    # IMPORTANT: Use --resume with explicit session ID instead of --continue
-    # --continue resumes the "most recent session in current directory" which
-    # can hijack active Claude Code sessions. --resume with a specific session ID
-    # ensures we only resume Ralph's own sessions. (Issue #151)
-    if [[ "$CLAUDE_USE_CONTINUE" == "true" && -n "$session_id" ]]; then
-        CLAUDE_CMD_ARGS+=("--resume" "$session_id")
-    fi
-    # If no session_id, start fresh - Claude will generate a new session ID
-    # which we'll capture via save_claude_session() for future loops
-
-    # Add loop context as system prompt (no escaping needed - array handles it)
-    if [[ -n "$loop_context" ]]; then
-        CLAUDE_CMD_ARGS+=("--append-system-prompt" "$loop_context")
-    fi
-
-    # Read prompt file content and use -p flag
-    # Note: Claude CLI uses -p for prompts, not --prompt-file (which doesn't exist)
-    # Array-based approach maintains shell injection safety
-    local prompt_content
-    prompt_content=$(cat "$prompt_file")
-    CLAUDE_CMD_ARGS+=("-p" "$prompt_content")
+    driver_build_command "$@"
 }
 
 # Main execution function
@@ -1418,6 +1385,14 @@ main() {
         fi
     fi
 
+    # Load platform driver (after .ralphrc so PLATFORM_DRIVER can be overridden)
+    load_platform_driver
+
+    # Validate --allowed-tools now that platform-specific VALID_TOOL_PATTERNS are loaded
+    if [[ "${_CLI_ALLOWED_TOOLS:-}" == "true" ]] && ! validate_allowed_tools "$CLAUDE_ALLOWED_TOOLS"; then
+        exit 1
+    fi
+
     log_status "SUCCESS" "🚀 Ralph loop starting with Claude Code"
     log_status "INFO" "Max calls per hour: $MAX_CALLS_PER_HOUR"
     log_status "INFO" "Logs: $LOG_DIR/ | Docs: $DOCS_DIR/ | Status: $STATUS_FILE"
@@ -1750,10 +1725,8 @@ while [[ $# -gt 0 ]]; do
             shift 2
             ;;
         --allowed-tools)
-            if ! validate_allowed_tools "$2"; then
-                exit 1
-            fi
             CLAUDE_ALLOWED_TOOLS="$2"
+            _CLI_ALLOWED_TOOLS=true
             shift 2
             ;;
         --no-continue)

package/ralph/templates/ralphrc.template

@@ -6,6 +6,13 @@
 # Values here override global Ralph defaults.
 # Environment variables override values in this file.
 
+# =============================================================================
+# PLATFORM DRIVER
+# =============================================================================
+
+# Platform driver for Ralph loop (claude-code or codex)
+PLATFORM_DRIVER="${PLATFORM_DRIVER:-claude-code}"
+
 # =============================================================================
 # PROJECT IDENTIFICATION
 # =============================================================================