ricecoder_hooks/
lib.rs

1//! RiceCoder Hooks System
2//!
3//! Event-driven automation through a registry of hooks that trigger on specific events.
4//!
5//! # Overview
6//!
7//! The Hooks System enables users to define automated actions that trigger on specific events.
8//! Hooks can execute shell commands, call ricecoder tools with parameter binding, send prompts
9//! to AI assistants, or trigger other hooks in chains.
10//!
11//! # Architecture
12//!
13//! The system consists of four main components:
14//!
15//! 1. **Hook Registry** (`registry`): Stores and manages hooks
16//! 2. **Event Dispatcher** (`dispatcher`): Routes events to matching hooks
17//! 3. **Hook Executor** (`executor`): Executes hook actions
18//! 4. **Configuration** (`config`): Loads and manages hook configuration
19//!
20//! # Quick Start
21//!
22//! ```ignore
23//! use ricecoder_hooks::{
24//!     InMemoryHookRegistry, Hook, Event, EventContext, Action, CommandAction,
25//! };
26//!
27//! // Create a registry
28//! let mut registry = InMemoryHookRegistry::new();
29//!
30//! // Create a hook
31//! let hook = Hook {
32//!     id: "format-hook".to_string(),
33//!     name: "Format on save".to_string(),
34//!     event: "file_modified".to_string(),
35//!     action: Action::Command(CommandAction {
36//!         command: "prettier".to_string(),
37//!         args: vec!["{{file_path}}".to_string()],
38//!         timeout_ms: Some(5000),
39//!         capture_output: true,
40//!     }),
41//!     enabled: true,
42//!     tags: vec!["formatting".to_string()],
43//!     metadata: serde_json::json!({}),
44//!     condition: None,
45//! };
46//!
47//! // Register the hook
48//! let hook_id = registry.register_hook(hook)?;
49//! println!("Registered hook: {}", hook_id);
50//!
51//! // Create an event
52//! let event = Event {
53//!     event_type: "file_modified".to_string(),
54//!     context: EventContext {
55//!         data: serde_json::json!({
56//!             "file_path": "/path/to/file.ts",
57//!             "old_hash": "abc123",
58//!             "new_hash": "def456",
59//!         }),
60//!         metadata: serde_json::json!({}),
61//!     },
62//!     timestamp: std::time::SystemTime::now(),
63//! };
64//!
65//! // Dispatch the event (hooks will be triggered)
66//! // dispatcher.dispatch_event(event)?;
67//! # Ok::<(), Box<dyn std::error::Error>>(())
68//! ```
69//!
70//! # Configuration
71//!
72//! Hooks are configured in YAML files (`.ricecoder/hooks.yaml`):
73//!
74//! ```yaml
75//! hooks:
76//!   - name: "Format on save"
77//!     event: "file_modified"
78//!     action:
79//!       type: "command"
80//!       command: "prettier"
81//!       args:
82//!         - "--write"
83//!         - "{{file_path}}"
84//!     enabled: true
85//! ```
86//!
87//! # Action Types
88//!
89//! Hooks support four action types:
90//!
91//! - **Command**: Execute shell commands
92//! - **Tool Call**: Call ricecoder tools with parameter binding
93//! - **AI Prompt**: Send prompts to AI assistants
94//! - **Chain**: Execute multiple hooks in sequence
95//!
96//! # Events
97//!
98//! The system emits events for:
99//!
100//! - File operations (created, modified, deleted, renamed, moved, read)
101//! - Directory operations (created, deleted)
102//! - System events (test passed/failed, generation complete, build complete, deployment complete)
103//!
104//! # Variable Substitution
105//!
106//! Variables are substituted in hook actions using `{{variable_name}}` syntax:
107//!
108//! ```yaml
109//! action:
110//!   type: "command"
111//!   command: "echo"
112//!   args:
113//!     - "File: {{file_path}}"
114//!     - "Size: {{file_size}}"
115//! ```
116//!
117//! Available variables depend on the event type. See the `events` module for details.
118//!
119//! # Error Handling
120//!
121//! All operations return `Result<T>` which is an alias for `std::result::Result<T, HooksError>`.
122//! Errors are explicit and provide context for debugging.
123//!
124//! # Thread Safety
125//!
126//! All components are thread-safe (`Send + Sync`) and can be used in concurrent contexts.
127
128pub mod cli;
129pub mod config;
130pub mod dispatcher;
131pub mod error;
132pub mod events;
133pub mod executor;
134pub mod registry;
135pub mod types;
136
137// Re-export public types
138pub use cli::{HookCli, HookCommand};
139pub use error::{HooksError, Result};
140pub use events::{
141    BuildFailedEvent, BuildSuccessEvent, CustomEvent, DeploymentCompleteEvent,
142    DirectoryOperationEvent, FileOperationEvent, FileSavedEvent, FileSystemMonitor,
143    GenerationCompleteEvent, RefactoringCompleteEvent, ReviewCompleteEvent, SystemEvent,
144    TestFailedEvent, TestPassedEvent,
145};
146pub use registry::{HookRegistry, InMemoryHookRegistry};
147pub use types::{
148    Action, AiPromptAction, ChainAction, CommandAction, Condition, Event, EventContext, Hook,
149    HookResult, HookStatus, ParameterBindings, ParameterValue, ToolCallAction,
150};
ricecoder_hooks/lib.rs

ricecoder_hooks/
lib.rs
