ralph_workflow/
lib.rs

1//! Ralph workflow library for AI agent orchestration.
2//!
3//! This crate provides the core functionality for the `ralph` CLI binary,
4//! implementing a reducer-based architecture for orchestrating AI coding agents
5//! through development and review cycles.
6//!
7//! # Quick Start
8//!
9//! Ralph is primarily a CLI binary. For library use (integration testing):
10//!
11//! ```toml
12//! [dev-dependencies]
13//! ralph-workflow = { version = "0.6", features = ["test-utils"] }
14//! ```
15//!
16//! # Architecture
17//!
18//! Ralph uses an **event-sourced reducer architecture**. The core state machine
19//! follows the pattern:
20//!
21//! ```text
22//! State → Orchestrator → Effect → Handler → Event → Reducer → State
23//! ```
24//!
25//! | Component | Pure? | Role |
26//! |-----------|-------|------|
27//! | [`reducer::PipelineState`] | Yes | Immutable progress snapshot, doubles as checkpoint |
28//! | [`reducer::reduce`] | Yes | `(State, Event) → State` |
29//! | [`reducer::determine_next_effect`] | Yes | `State → Effect` |
30//! | [`reducer::EffectHandler`] | No | Executes effects, produces events |
31//!
32//! Business logic lives in reducers (pure). I/O lives in handlers (impure).
33//!
34//! ## Two Effect Layers
35//!
36//! Ralph has two distinct effect types for different pipeline stages:
37//!
38//! | Layer | Module | When | Filesystem Access |
39//! |-------|--------|------|-------------------|
40//! | `AppEffect` | [`app`] | Before repo root known | `std::fs` directly |
41//! | `Effect` | [`reducer`] | After repo root known | Via [`workspace::Workspace`] |
42//!
43//! These layers must never mix: `AppEffect` cannot use `Workspace`, and `Effect`
44//! cannot use `std::fs` directly.
45//!
46//! # I/O Abstractions
47//!
48//! All I/O is abstracted through traits for testability:
49//!
50//! - [`workspace::Workspace`] - Filesystem operations
51//!   - Production: [`workspace::WorkspaceFs`]
52//!   - Tests: `MemoryWorkspace` (with `test-utils` feature)
53//! - [`ProcessExecutor`] - Process spawning
54//!   - Production: [`RealProcessExecutor`]
55//!   - Tests: `MockProcessExecutor` (with `test-utils` feature)
56//!
57//! # Feature Flags
58//!
59//! - `monitoring` (default) - Enable streaming metrics and debugging APIs
60//! - `test-utils` - Enable test utilities (`MockProcessExecutor`, `MemoryWorkspace`, etc.)
61//! - `hardened-resume` (default) - Enable checkpoint file state capture for recovery
62//!
63//! # Key Modules
64//!
65//! **Core Architecture:**
66//! - [`reducer`] - Core state machine with pure reducers and effect handlers
67//! - [`app`] - CLI layer operating before repo root is known (`AppEffect`)
68//! - [`phases`] - Pipeline phase implementations (planning, development, review, commit)
69//!
70//! **I/O Abstractions:**
71//! - [`workspace`] - Filesystem abstraction (`WorkspaceFs` production, `MemoryWorkspace` testing)
72//! - [`executor`] - Process execution abstraction for agent spawning
73//!
74//! **Agent Infrastructure:**
75//! - [`agents`] - Agent configuration, registry, and CCS (Claude Code Switch) support
76//! - [`json_parser`] - NDJSON streaming parsers for Claude, Codex, Gemini, OpenCode
77//! - [`prompts`] - Template system for agent prompts
78//!
79//! **Supporting:**
80//! - [`git_helpers`] - Git operations using libgit2 (no CLI dependency)
81//! - [`checkpoint`] - Pipeline state persistence for `--resume` support
82//! - [`config`] - Configuration loading and verbosity levels
83//!
84//! # Error Handling
85//!
86//! Most functions return `anyhow::Result` for flexible error handling with context.
87//! Use `.context()` to add context to errors as they propagate.
88
89pub mod agents;
90pub mod app;
91pub mod banner;
92pub mod checkpoint;
93pub mod cli;
94pub mod common;
95pub mod config;
96pub mod diagnostics;
97pub mod executor;
98pub mod files;
99pub mod git_helpers;
100pub mod guidelines;
101pub mod interrupt;
102pub mod json_parser;
103pub mod language_detector;
104pub mod logger;
105pub mod logging;
106pub mod phases;
107pub mod pipeline;
108pub mod platform;
109pub mod prompts;
110pub mod reducer;
111pub mod rendering;
112pub mod review_metrics;
113pub mod templates;
114pub mod workspace;
115
116// Re-export XML extraction and validation functions for use in integration tests.
117// These functions parse and validate XML output from agent responses (plan, issues, fix results).
118pub use files::llm_output_extraction::extract_development_result_xml;
119pub use files::llm_output_extraction::extract_fix_result_xml;
120pub use files::llm_output_extraction::extract_issues_xml;
121pub use files::llm_output_extraction::validate_development_result_xml;
122pub use files::llm_output_extraction::validate_fix_result_xml;
123pub use files::llm_output_extraction::validate_issues_xml;
124
125// Re-export process executor types for dependency injection.
126// See [`executor`] module for documentation.
127pub use executor::{
128    AgentChild, AgentChildHandle, AgentCommandResult, AgentSpawnConfig, ProcessExecutor,
129    ProcessOutput, RealAgentChild, RealProcessExecutor,
130};
131
132// Re-export mock executor for test-utils feature.
133// Use MockProcessExecutor to control process behavior in integration tests.
134#[cfg(any(test, feature = "test-utils"))]
135pub use executor::{MockAgentChild, MockProcessExecutor};
ralph_workflow/lib.rs

ralph_workflow/
lib.rs
