sal/rhai_integration_plan.md

Implementation Plan: Rhai Integration for OS Module Functions

1. Project Structure Changes

We'll create a new directory structure for the Rhai integration:

src/
├── rhai/
│   ├── mod.rs         # Main module file for Rhai integration
│   ├── os.rs          # OS module wrappers
│   └── error.rs       # Error type conversions

2. Dependencies

Add Rhai as a dependency in Cargo.toml:

[dependencies]
# Existing dependencies...
rhai = { version = "1.12.0", features = ["sync"] }

3. Implementation Steps

3.1. Create Basic Module Structure

1. Create the src/rhai/mod.rs file with:

   • Module declarations
   • A modular registration system
   • Public exports

2. Create the src/rhai/error.rs file with:

   • Conversions from our custom error types to Rhai's EvalAltResult
   • Helper functions for error handling

3.2. Implement OS Module Wrappers

Create the src/rhai/os.rs file with:

1. Import necessary modules and types
2. Create wrapper functions for each function in src/os/fs.rs and src/os/download.rs
3. Implement a registration function specific to the OS module
4. Expose error types to Rhai

3.3. Update Main Library File

Update src/lib.rs to expose the new Rhai module.

4. Detailed Implementation

4.1. Error Handling

For each function that returns a Result<T, E> where E is one of our custom error types:

1. Create a wrapper function that converts our error type to Rhai's EvalAltResult
2. Register the error types with Rhai to allow for proper error handling in scripts

4.2. Function Wrappers

For each function in the OS module:

1. Create a wrapper function with the same name
2. Handle any necessary type conversions
3. Convert error types to Rhai's error system
4. Register the function with the Rhai engine

4.3. Registration System

Create a modular registration system:

1. Implement a general register function that takes a Rhai engine
2. Implement module-specific registration functions (e.g., register_os_module)
3. Design the system to be extensible for future modules

5. Implementation Flow Diagram

flowchart TD
    A[Add Rhai dependency] --> B[Create directory structure]
    B --> C[Implement error conversions]
    C --> D[Implement OS module wrappers]
    D --> E[Create registration system]
    E --> F[Update lib.rs]
    F --> G[Test the implementation]

6. Function Mapping

Here's a mapping of the OS module functions to their Rhai wrappers:

File System Functions (from fs.rs)

• copy → Wrap with error conversion
• exist → Direct wrapper (returns bool)
• find_file → Wrap with error conversion
• find_files → Wrap with error conversion
• find_dir → Wrap with error conversion
• find_dirs → Wrap with error conversion
• delete → Wrap with error conversion
• mkdir → Wrap with error conversion
• file_size → Wrap with error conversion
• rsync → Wrap with error conversion

Download Functions (from download.rs)

• download → Wrap with error conversion
• download_install → Wrap with error conversion

7. Error Type Handling

We'll expose our custom error types to Rhai:

1. Register FsError and DownloadError as custom types
2. Implement proper error conversion to allow for detailed error handling in Rhai scripts
3. Create helper functions to extract error information

8. Testing Strategy

1. Create unit tests for each wrapper function
2. Create integration tests with sample Rhai scripts
3. Test error handling scenarios