Crate ricecoder_hooks 

RiceCoder Hooks System

Event-driven automation through a registry of hooks that trigger on specific events.

Overview

The Hooks System enables users to define automated actions that trigger on specific events. Hooks can execute shell commands, call ricecoder tools with parameter binding, send prompts to AI assistants, or trigger other hooks in chains.

Architecture

The system consists of four main components:

1. Hook Registry (registry): Stores and manages hooks
2. Event Dispatcher (dispatcher): Routes events to matching hooks
3. Hook Executor (executor): Executes hook actions
4. Configuration (config): Loads and manages hook configuration

Quick Start

use ricecoder_hooks::{
    InMemoryHookRegistry, Hook, Event, EventContext, Action, CommandAction,
};

// Create a registry
let mut registry = InMemoryHookRegistry::new();

// Create a hook
let hook = Hook {
    id: "format-hook".to_string(),
    name: "Format on save".to_string(),
    event: "file_modified".to_string(),
    action: Action::Command(CommandAction {
        command: "prettier".to_string(),
        args: vec!["{{file_path}}".to_string()],
        timeout_ms: Some(5000),
        capture_output: true,
    }),
    enabled: true,
    tags: vec!["formatting".to_string()],
    metadata: serde_json::json!({}),
    condition: None,
};

// Register the hook
let hook_id = registry.register_hook(hook)?;
println!("Registered hook: {}", hook_id);

// Create an event
let event = Event {
    event_type: "file_modified".to_string(),
    context: EventContext {
        data: serde_json::json!({
            "file_path": "/path/to/file.ts",
            "old_hash": "abc123",
            "new_hash": "def456",
        }),
        metadata: serde_json::json!({}),
    },
    timestamp: std::time::SystemTime::now(),
};

// Dispatch the event (hooks will be triggered)
// dispatcher.dispatch_event(event)?;

Configuration

Hooks are configured in YAML files (.ricecoder/hooks.yaml):

hooks:
  - name: "Format on save"
    event: "file_modified"
    action:
      type: "command"
      command: "prettier"
      args:
        - "--write"
        - "{{file_path}}"
    enabled: true

Action Types

Hooks support four action types:

• Command: Execute shell commands
• Tool Call: Call ricecoder tools with parameter binding
• AI Prompt: Send prompts to AI assistants
• Chain: Execute multiple hooks in sequence

Events

The system emits events for:

• File operations (created, modified, deleted, renamed, moved, read)
• Directory operations (created, deleted)
• System events (test passed/failed, generation complete, build complete, deployment complete)

Variable Substitution

Variables are substituted in hook actions using {{variable_name}} syntax:

action:
  type: "command"
  command: "echo"
  args:
    - "File: {{file_path}}"
    - "Size: {{file_size}}"

Available variables depend on the event type. See the events module for details.

Error Handling

All operations return Result<T> which is an alias for std::result::Result<T, HooksError>. Errors are explicit and provide context for debugging.

Thread Safety

All components are thread-safe (Send + Sync) and can be used in concurrent contexts.

Re-exports

pub use cli::HookCli;

pub use cli::HookCommand;

pub use error::HooksError;

pub use error::Result;

pub use events::BuildFailedEvent;

pub use events::BuildSuccessEvent;

pub use events::CustomEvent;

pub use events::DeploymentCompleteEvent;

pub use events::DirectoryOperationEvent;

pub use events::FileOperationEvent;

pub use events::FileSavedEvent;

pub use events::FileSystemMonitor;

pub use events::GenerationCompleteEvent;

pub use events::RefactoringCompleteEvent;

pub use events::ReviewCompleteEvent;

pub use events::SystemEvent;

pub use events::TestFailedEvent;

pub use events::TestPassedEvent;

pub use registry::HookRegistry;

pub use registry::InMemoryHookRegistry;

pub use types::Action;

pub use types::AiPromptAction;

pub use types::ChainAction;

pub use types::CommandAction;

pub use types::Condition;

pub use types::Event;

pub use types::EventContext;

pub use types::Hook;

pub use types::HookResult;

pub use types::HookStatus;

pub use types::ParameterBindings;

pub use types::ParameterValue;

pub use types::ToolCallAction;

Modules

cli

CLI commands for hook management

config

Hook configuration loading and management

dispatcher

Event dispatcher for triggering hooks

error

Error types for the hooks system

events

Event types for the hooks system

executor

Hook execution engine

registry

Hook registry for storing and managing hooks

types

Core data types for the hooks system