bmalph 1.0.0

package/dist/utils/json.js

@@ -0,0 +1,26 @@
+import { readFile } from "fs/promises";
+/**
+ * Reads and parses a JSON file with proper error discrimination:
+ * - File not found → returns null
+ * - Parse error → throws
+ * - Permission error → throws
+ */
+export async function readJsonFile(path) {
+    let content;
+    try {
+        content = await readFile(path, "utf-8");
+    }
+    catch (err) {
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            return null;
+        }
+        throw err;
+    }
+    try {
+        return JSON.parse(content);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Invalid JSON in ${path}: ${message}`);
+    }
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,3 @@
+export declare function setVerbose(value: boolean): void;
+export declare function isVerbose(): boolean;
+export declare function debug(message: string): void;

package/dist/utils/logger.js

@@ -0,0 +1,13 @@
+import chalk from "chalk";
+let verbose = false;
+export function setVerbose(value) {
+    verbose = value;
+}
+export function isVerbose() {
+    return verbose;
+}
+export function debug(message) {
+    if (verbose) {
+        console.log(chalk.dim(`[debug] ${message}`));
+    }
+}

package/dist/utils/state.d.ts

@@ -0,0 +1,29 @@
+export interface BmalphState {
+    currentPhase: number;
+    status: "planning" | "implementing" | "completed";
+    startedAt: string;
+    lastUpdated: string;
+}
+export interface PhaseCommand {
+    code: string;
+    name: string;
+    agent: string;
+    description: string;
+    required: boolean;
+}
+export interface PhaseInfo {
+    name: string;
+    agent: string;
+    commands: PhaseCommand[];
+}
+export declare function readState(projectDir: string): Promise<BmalphState | null>;
+export declare function writeState(projectDir: string, state: BmalphState): Promise<void>;
+export declare function getPhaseLabel(phase: number): string;
+export declare function getPhaseInfo(phase: number): PhaseInfo;
+export interface RalphStatus {
+    loopCount: number;
+    status: "running" | "blocked" | "completed" | "not_started";
+    tasksCompleted: number;
+    tasksTotal: number;
+}
+export declare function readRalphStatus(projectDir: string): Promise<RalphStatus>;

package/dist/utils/state.js

@@ -0,0 +1,78 @@
+import { writeFile, mkdir, rename } from "fs/promises";
+import { join } from "path";
+import { readJsonFile } from "./json.js";
+import { validateState } from "./validate.js";
+const STATE_DIR = "bmalph/state";
+export async function readState(projectDir) {
+    const data = await readJsonFile(join(projectDir, STATE_DIR, "current-phase.json"));
+    if (data === null)
+        return null;
+    return validateState(data);
+}
+export async function writeState(projectDir, state) {
+    await mkdir(join(projectDir, STATE_DIR), { recursive: true });
+    const target = join(projectDir, STATE_DIR, "current-phase.json");
+    const tmp = target + ".tmp";
+    await writeFile(tmp, JSON.stringify(state, null, 2) + "\n");
+    await rename(tmp, target);
+}
+export function getPhaseLabel(phase) {
+    const labels = {
+        1: "Analysis",
+        2: "Planning",
+        3: "Solutioning",
+        4: "Implementation",
+    };
+    return labels[phase] ?? "Unknown";
+}
+export function getPhaseInfo(phase) {
+    const info = {
+        1: {
+            name: "Analysis",
+            agent: "Analyst",
+            commands: [
+                { code: "BP", name: "Brainstorm Project", agent: "analyst", description: "Expert guided facilitation through brainstorming techniques", required: false },
+                { code: "MR", name: "Market Research", agent: "analyst", description: "Market analysis, competitive landscape, customer needs", required: false },
+                { code: "DR", name: "Domain Research", agent: "analyst", description: "Industry domain deep dive, subject matter expertise", required: false },
+                { code: "TR", name: "Technical Research", agent: "analyst", description: "Technical feasibility, architecture options", required: false },
+                { code: "CB", name: "Create Brief", agent: "analyst", description: "Guided experience to nail down your product idea", required: false },
+                { code: "VB", name: "Validate Brief", agent: "analyst", description: "Validates product brief completeness", required: false },
+            ],
+        },
+        2: {
+            name: "Planning",
+            agent: "PM (John)",
+            commands: [
+                { code: "CP", name: "Create PRD", agent: "pm", description: "Expert led facilitation to produce your PRD", required: true },
+                { code: "VP", name: "Validate PRD", agent: "pm", description: "Validate PRD is comprehensive and cohesive", required: false },
+                { code: "CU", name: "Create UX", agent: "ux-designer", description: "Guidance through realizing the plan for your UX", required: false },
+                { code: "VU", name: "Validate UX", agent: "ux-designer", description: "Validates UX design deliverables", required: false },
+            ],
+        },
+        3: {
+            name: "Solutioning",
+            agent: "Architect",
+            commands: [
+                { code: "CA", name: "Create Architecture", agent: "architect", description: "Guided workflow to document technical decisions", required: true },
+                { code: "VA", name: "Validate Architecture", agent: "architect", description: "Validates architecture completeness", required: false },
+                { code: "CE", name: "Create Epics and Stories", agent: "pm", description: "Create the epics and stories listing", required: true },
+                { code: "VE", name: "Validate Epics and Stories", agent: "pm", description: "Validates epics and stories completeness", required: false },
+                { code: "TD", name: "Test Design", agent: "tea", description: "Create comprehensive test scenarios", required: false },
+                { code: "IR", name: "Implementation Readiness", agent: "architect", description: "Ensure PRD, UX, architecture, and stories are aligned", required: true },
+            ],
+        },
+        4: {
+            name: "Implementation",
+            agent: "Developer (Amelia)",
+            commands: [],
+        },
+    };
+    return info[phase] ?? { name: "Unknown", agent: "Unknown", commands: [] };
+}
+export async function readRalphStatus(projectDir) {
+    const data = await readJsonFile(join(projectDir, ".ralph/status.json"));
+    if (data === null) {
+        return { loopCount: 0, status: "not_started", tasksCompleted: 0, tasksTotal: 0 };
+    }
+    return data;
+}

package/dist/utils/validate.d.ts

@@ -0,0 +1,4 @@
+import type { BmalphConfig } from "./config.js";
+import type { BmalphState } from "./state.js";
+export declare function validateConfig(data: unknown): BmalphConfig;
+export declare function validateState(data: unknown): BmalphState;

package/dist/utils/validate.js

@@ -0,0 +1,42 @@
+const VALID_STATUSES = ["planning", "implementing", "completed"];
+function assertObject(data, label) {
+    if (data === null || data === undefined || typeof data !== "object" || Array.isArray(data)) {
+        throw new Error(`${label}: expected an object`);
+    }
+}
+export function validateConfig(data) {
+    assertObject(data, "config");
+    if (typeof data.name !== "string") {
+        throw new Error("config.name must be a string");
+    }
+    if (typeof data.createdAt !== "string") {
+        throw new Error("config.createdAt must be a string");
+    }
+    const description = typeof data.description === "string" ? data.description : "";
+    return {
+        name: data.name,
+        description,
+        createdAt: data.createdAt,
+    };
+}
+export function validateState(data) {
+    assertObject(data, "state");
+    if (typeof data.currentPhase !== "number") {
+        throw new Error("state.currentPhase must be a number");
+    }
+    if (typeof data.status !== "string" || !VALID_STATUSES.includes(data.status)) {
+        throw new Error(`state.status must be one of: ${VALID_STATUSES.join(", ")}`);
+    }
+    if (typeof data.startedAt !== "string") {
+        throw new Error("state.startedAt must be a string");
+    }
+    if (typeof data.lastUpdated !== "string") {
+        throw new Error("state.lastUpdated must be a string");
+    }
+    return {
+        currentPhase: data.currentPhase,
+        status: data.status,
+        startedAt: data.startedAt,
+        lastUpdated: data.lastUpdated,
+    };
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "bmalph",
+  "version": "1.0.0",
+  "description": "Unified AI Development Framework - BMAD phases with Ralph execution loop for Claude Code",
+  "type": "module",
+  "bin": {
+    "bmalph": "./bin/bmalph.js"
+  },
+  "scripts": {
+    "prepare": "tsc",
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src tests",
+    "format": "prettier --write .",
+    "prepublishOnly": "npm run lint && npm run build && npm test"
+  },
+  "keywords": [
+    "claude",
+    "ai",
+    "development",
+    "framework",
+    "agents"
+  ],
+  "author": "Lars Cowe",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LarsCowe/bmalph.git"
+  },
+  "homepage": "https://github.com/LarsCowe/bmalph#readme",
+  "bugs": {
+    "url": "https://github.com/LarsCowe/bmalph/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "bmad/",
+    "ralph/",
+    "slash-commands/"
+  ],
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "inquirer": "^13.2.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^25.0.10",
+    "eslint": "^9.39.2",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.53.1",
+    "vitest": "^4.0.18"
+  }
+}

package/ralph/lib/circuit_breaker.sh

@@ -0,0 +1,330 @@
+#!/bin/bash
+# Circuit Breaker Component for Ralph
+# Prevents runaway token consumption by detecting stagnation
+# Based on Michael Nygard's "Release It!" pattern
+
+# Source date utilities for cross-platform compatibility
+source "$(dirname "${BASH_SOURCE[0]}")/date_utils.sh"
+
+# Circuit Breaker States
+CB_STATE_CLOSED="CLOSED"        # Normal operation, progress detected
+CB_STATE_HALF_OPEN="HALF_OPEN"  # Monitoring mode, checking for recovery
+CB_STATE_OPEN="OPEN"            # Failure detected, execution halted
+
+# Circuit Breaker Configuration
+# Use RALPH_DIR if set by main script, otherwise default to .ralph
+RALPH_DIR="${RALPH_DIR:-.ralph}"
+CB_STATE_FILE="$RALPH_DIR/.circuit_breaker_state"
+CB_HISTORY_FILE="$RALPH_DIR/.circuit_breaker_history"
+CB_NO_PROGRESS_THRESHOLD=3      # Open circuit after N loops with no progress
+CB_SAME_ERROR_THRESHOLD=5       # Open circuit after N loops with same error
+CB_OUTPUT_DECLINE_THRESHOLD=70  # Open circuit if output declines by >70%
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# Initialize circuit breaker
+init_circuit_breaker() {
+    # Check if state file exists and is valid JSON
+    if [[ -f "$CB_STATE_FILE" ]]; then
+        if ! jq '.' "$CB_STATE_FILE" > /dev/null 2>&1; then
+            # Corrupted, recreate
+            rm -f "$CB_STATE_FILE"
+        fi
+    fi
+
+    if [[ ! -f "$CB_STATE_FILE" ]]; then
+        cat > "$CB_STATE_FILE" << EOF
+{
+    "state": "$CB_STATE_CLOSED",
+    "last_change": "$(get_iso_timestamp)",
+    "consecutive_no_progress": 0,
+    "consecutive_same_error": 0,
+    "last_progress_loop": 0,
+    "total_opens": 0,
+    "reason": ""
+}
+EOF
+    fi
+
+    # Check if history file exists and is valid JSON
+    if [[ -f "$CB_HISTORY_FILE" ]]; then
+        if ! jq '.' "$CB_HISTORY_FILE" > /dev/null 2>&1; then
+            # Corrupted, recreate
+            rm -f "$CB_HISTORY_FILE"
+        fi
+    fi
+
+    if [[ ! -f "$CB_HISTORY_FILE" ]]; then
+        echo '[]' > "$CB_HISTORY_FILE"
+    fi
+}
+
+# Get current circuit breaker state
+get_circuit_state() {
+    if [[ ! -f "$CB_STATE_FILE" ]]; then
+        echo "$CB_STATE_CLOSED"
+        return
+    fi
+
+    jq -r '.state' "$CB_STATE_FILE" 2>/dev/null || echo "$CB_STATE_CLOSED"
+}
+
+# Check if circuit breaker allows execution
+can_execute() {
+    local state=$(get_circuit_state)
+
+    if [[ "$state" == "$CB_STATE_OPEN" ]]; then
+        return 1  # Circuit is open, cannot execute
+    else
+        return 0  # Circuit is closed or half-open, can execute
+    fi
+}
+
+# Record loop execution result
+record_loop_result() {
+    local loop_number=$1
+    local files_changed=$2
+    local has_errors=$3
+    local output_length=$4
+
+    init_circuit_breaker
+
+    local state_data=$(cat "$CB_STATE_FILE")
+    local current_state=$(echo "$state_data" | jq -r '.state')
+    local consecutive_no_progress=$(echo "$state_data" | jq -r '.consecutive_no_progress' | tr -d '[:space:]')
+    local consecutive_same_error=$(echo "$state_data" | jq -r '.consecutive_same_error' | tr -d '[:space:]')
+    local last_progress_loop=$(echo "$state_data" | jq -r '.last_progress_loop' | tr -d '[:space:]')
+
+    # Ensure integers
+    consecutive_no_progress=$((consecutive_no_progress + 0))
+    consecutive_same_error=$((consecutive_same_error + 0))
+    last_progress_loop=$((last_progress_loop + 0))
+
+    # Detect progress
+    local has_progress=false
+    if [[ $files_changed -gt 0 ]]; then
+        has_progress=true
+        consecutive_no_progress=0
+        last_progress_loop=$loop_number
+    else
+        consecutive_no_progress=$((consecutive_no_progress + 1))
+    fi
+
+    # Detect same error repetition
+    if [[ "$has_errors" == "true" ]]; then
+        consecutive_same_error=$((consecutive_same_error + 1))
+    else
+        consecutive_same_error=0
+    fi
+
+    # Determine new state and reason
+    local new_state="$current_state"
+    local reason=""
+
+    # State transitions
+    case $current_state in
+        "$CB_STATE_CLOSED")
+            # Normal operation - check for failure conditions
+            if [[ $consecutive_no_progress -ge $CB_NO_PROGRESS_THRESHOLD ]]; then
+                new_state="$CB_STATE_OPEN"
+                reason="No progress detected in $consecutive_no_progress consecutive loops"
+            elif [[ $consecutive_same_error -ge $CB_SAME_ERROR_THRESHOLD ]]; then
+                new_state="$CB_STATE_OPEN"
+                reason="Same error repeated in $consecutive_same_error consecutive loops"
+            elif [[ $consecutive_no_progress -ge 2 ]]; then
+                new_state="$CB_STATE_HALF_OPEN"
+                reason="Monitoring: $consecutive_no_progress loops without progress"
+            fi
+            ;;
+
+        "$CB_STATE_HALF_OPEN")
+            # Monitoring mode - either recover or fail
+            if [[ "$has_progress" == "true" ]]; then
+                new_state="$CB_STATE_CLOSED"
+                reason="Progress detected, circuit recovered"
+            elif [[ $consecutive_no_progress -ge $CB_NO_PROGRESS_THRESHOLD ]]; then
+                new_state="$CB_STATE_OPEN"
+                reason="No recovery, opening circuit after $consecutive_no_progress loops"
+            fi
+            ;;
+
+        "$CB_STATE_OPEN")
+            # Circuit is open - stays open (manual intervention required)
+            reason="Circuit breaker is open, execution halted"
+            ;;
+    esac
+
+    # Update state file
+    local total_opens=$(echo "$state_data" | jq -r '.total_opens' | tr -d '[:space:]')
+    total_opens=$((total_opens + 0))
+    if [[ "$new_state" == "$CB_STATE_OPEN" && "$current_state" != "$CB_STATE_OPEN" ]]; then
+        total_opens=$((total_opens + 1))
+    fi
+
+    cat > "$CB_STATE_FILE" << EOF
+{
+    "state": "$new_state",
+    "last_change": "$(get_iso_timestamp)",
+    "consecutive_no_progress": $consecutive_no_progress,
+    "consecutive_same_error": $consecutive_same_error,
+    "last_progress_loop": $last_progress_loop,
+    "total_opens": $total_opens,
+    "reason": "$reason",
+    "current_loop": $loop_number
+}
+EOF
+
+    # Log state transition
+    if [[ "$new_state" != "$current_state" ]]; then
+        log_circuit_transition "$current_state" "$new_state" "$reason" "$loop_number"
+    fi
+
+    # Return exit code based on new state
+    if [[ "$new_state" == "$CB_STATE_OPEN" ]]; then
+        return 1  # Circuit opened, signal to stop
+    else
+        return 0  # Can continue
+    fi
+}
+
+# Log circuit breaker state transitions
+log_circuit_transition() {
+    local from_state=$1
+    local to_state=$2
+    local reason=$3
+    local loop_number=$4
+
+    local history=$(cat "$CB_HISTORY_FILE")
+    local transition="{
+        \"timestamp\": \"$(get_iso_timestamp)\",
+        \"loop\": $loop_number,
+        \"from_state\": \"$from_state\",
+        \"to_state\": \"$to_state\",
+        \"reason\": \"$reason\"
+    }"
+
+    history=$(echo "$history" | jq ". += [$transition]")
+    echo "$history" > "$CB_HISTORY_FILE"
+
+    # Console log with colors
+    case $to_state in
+        "$CB_STATE_OPEN")
+            echo -e "${RED}🚨 CIRCUIT BREAKER OPENED${NC}"
+            echo -e "${RED}Reason: $reason${NC}"
+            ;;
+        "$CB_STATE_HALF_OPEN")
+            echo -e "${YELLOW}⚠️  CIRCUIT BREAKER: Monitoring Mode${NC}"
+            echo -e "${YELLOW}Reason: $reason${NC}"
+            ;;
+        "$CB_STATE_CLOSED")
+            echo -e "${GREEN}✅ CIRCUIT BREAKER: Normal Operation${NC}"
+            echo -e "${GREEN}Reason: $reason${NC}"
+            ;;
+    esac
+}
+
+# Display circuit breaker status
+show_circuit_status() {
+    init_circuit_breaker
+
+    local state_data=$(cat "$CB_STATE_FILE")
+    local state=$(echo "$state_data" | jq -r '.state')
+    local reason=$(echo "$state_data" | jq -r '.reason')
+    local no_progress=$(echo "$state_data" | jq -r '.consecutive_no_progress')
+    local last_progress=$(echo "$state_data" | jq -r '.last_progress_loop')
+    local current_loop=$(echo "$state_data" | jq -r '.current_loop')
+    local total_opens=$(echo "$state_data" | jq -r '.total_opens')
+
+    local color=""
+    local status_icon=""
+
+    case $state in
+        "$CB_STATE_CLOSED")
+            color=$GREEN
+            status_icon="✅"
+            ;;
+        "$CB_STATE_HALF_OPEN")
+            color=$YELLOW
+            status_icon="⚠️ "
+            ;;
+        "$CB_STATE_OPEN")
+            color=$RED
+            status_icon="🚨"
+            ;;
+    esac
+
+    echo -e "${color}╔════════════════════════════════════════════════════════════╗${NC}"
+    echo -e "${color}║           Circuit Breaker Status                          ║${NC}"
+    echo -e "${color}╚════════════════════════════════════════════════════════════╝${NC}"
+    echo -e "${color}State:${NC}                 $status_icon $state"
+    echo -e "${color}Reason:${NC}                $reason"
+    echo -e "${color}Loops since progress:${NC} $no_progress"
+    echo -e "${color}Last progress:${NC}        Loop #$last_progress"
+    echo -e "${color}Current loop:${NC}         #$current_loop"
+    echo -e "${color}Total opens:${NC}          $total_opens"
+    echo ""
+}
+
+# Reset circuit breaker (for manual intervention)
+reset_circuit_breaker() {
+    local reason=${1:-"Manual reset"}
+
+    cat > "$CB_STATE_FILE" << EOF
+{
+    "state": "$CB_STATE_CLOSED",
+    "last_change": "$(get_iso_timestamp)",
+    "consecutive_no_progress": 0,
+    "consecutive_same_error": 0,
+    "last_progress_loop": 0,
+    "total_opens": 0,
+    "reason": "$reason"
+}
+EOF
+
+    echo -e "${GREEN}✅ Circuit breaker reset to CLOSED state${NC}"
+}
+
+# Check if loop should halt (used in main loop)
+should_halt_execution() {
+    local state=$(get_circuit_state)
+
+    if [[ "$state" == "$CB_STATE_OPEN" ]]; then
+        show_circuit_status
+        echo ""
+        echo -e "${RED}╔════════════════════════════════════════════════════════════╗${NC}"
+        echo -e "${RED}║  EXECUTION HALTED: Circuit Breaker Opened                 ║${NC}"
+        echo -e "${RED}╚════════════════════════════════════════════════════════════╝${NC}"
+        echo ""
+        echo -e "${YELLOW}Ralph has detected that no progress is being made.${NC}"
+        echo ""
+        echo -e "${YELLOW}Possible reasons:${NC}"
+        echo "  • Project may be complete (check .ralph/@fix_plan.md)"
+        echo "  • Claude may be stuck on an error"
+        echo "  • .ralph/PROMPT.md may need clarification"
+        echo "  • Manual intervention may be required"
+        echo ""
+        echo -e "${YELLOW}To continue:${NC}"
+        echo "  1. Review recent logs: tail -20 .ralph/logs/ralph.log"
+        echo "  2. Check Claude output: ls -lt .ralph/logs/claude_output_*.log | head -1"
+        echo "  3. Update .ralph/@fix_plan.md if needed"
+        echo "  4. Reset circuit breaker: ralph --reset-circuit"
+        echo ""
+        return 0  # Signal to halt
+    else
+        return 1  # Can continue
+    fi
+}
+
+# Export functions
+export -f init_circuit_breaker
+export -f get_circuit_state
+export -f can_execute
+export -f record_loop_result
+export -f show_circuit_status
+export -f reset_circuit_breaker
+export -f should_halt_execution

package/ralph/lib/date_utils.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+
+# date_utils.sh - Cross-platform date utility functions
+# Provides consistent date formatting and arithmetic across GNU (Linux) and BSD (macOS) systems
+
+# Get current timestamp in ISO 8601 format with seconds precision
+# Returns: YYYY-MM-DDTHH:MM:SS+00:00 format
+get_iso_timestamp() {
+    local os_type
+    os_type=$(uname)
+
+    if [[ "$os_type" == "Darwin" ]]; then
+        # macOS (BSD date)
+        # Use manual formatting and add colon to timezone offset
+        date -u +"%Y-%m-%dT%H:%M:%S%z" | sed 's/\(..\)$/:\1/'
+    else
+        # Linux (GNU date) - use -u flag for UTC
+        date -u -Iseconds
+    fi
+}
+
+# Get time component (HH:MM:SS) for one hour from now
+# Returns: HH:MM:SS format
+get_next_hour_time() {
+    local os_type
+    os_type=$(uname)
+
+    if [[ "$os_type" == "Darwin" ]]; then
+        # macOS (BSD date) - use -v flag for date arithmetic
+        date -v+1H '+%H:%M:%S'
+    else
+        # Linux (GNU date) - use -d flag for date arithmetic
+        date -d '+1 hour' '+%H:%M:%S'
+    fi
+}
+
+# Get current timestamp in a basic format (fallback)
+# Returns: YYYY-MM-DD HH:MM:SS format
+get_basic_timestamp() {
+    date '+%Y-%m-%d %H:%M:%S'
+}
+
+# Get current Unix epoch time in seconds
+# Returns: Integer seconds since 1970-01-01 00:00:00 UTC
+get_epoch_seconds() {
+    date +%s
+}
+
+# Export functions for use in other scripts
+export -f get_iso_timestamp
+export -f get_next_hour_time
+export -f get_basic_timestamp
+export -f get_epoch_seconds