osiris/PREDEFINED_INSTANCES.md

# OSIRIS Predefined Instances ✅

OSIRIS runner now supports predefined instances that are automatically available in your Rhai scripts without needing to create them manually.

## 🎉 Status: FULLY OPERATIONAL

```
✅ CLI argument parsing for instances
✅ Automatic instance creation
✅ Global scope injection
✅ Multiple instances support
✅ Test script working
```

## 🚀 Quick Start

### Define Instances via CLI

```bash
cargo run --bin runner --features rhai-support -- runner1 \
  --instance freezone:redis://localhost:6379:1 \
  --instance my:redis://localhost:6379:2 \
  --script-file scripts/predefined_instances.rhai
```

### Use Them Directly in Scripts

```rhai
// No need to create instances - they're already available!
freezone.put_note(my_note);
my.put_note(my_note);
```

## 📝 Complete Example

### Command Line

```bash
cargo run --bin runner --features rhai-support -- test1 \
  --instance freezone:redis://localhost:6379:1 \
  --instance my:redis://localhost:6379:2 \
  --script-file scripts/predefined_instances.rhai
```

### Script (scripts/predefined_instances.rhai)

```rhai
print("=== Predefined Instances Example ===");

// freezone and my are already available!
print(`Using: ${freezone.name()}`);
print(`Using: ${my.name()}`);

// Create a note
let my_note = note("notes")
    .title("Test Note")
    .content("Using predefined instances!");

// Use them directly - no setup needed!
freezone.put_note(my_note);
my.put_note(my_note);

// Query each instance
let ids1 = freezone.query("notes", "title", "Test Note");
let ids2 = my.query("notes", "title", "Test Note");
```

### Output

```
🚀 OSIRIS Runner
Runner ID: test1
HeroDB: redis://localhost:6379 (DB 1)
  Instance: freezone → redis://localhost:6379 (DB 1)
  Instance: my → redis://localhost:6379 (DB 2)

📝 Executing script...

─────────────────────────────────────
=== Predefined Instances Example ===

Using predefined instance: freezone
Using predefined instance: my

Creating note...
Note created: Predefined Instance Test

Storing in freezone...
✓ Stored in freezone: 61ea54fe-504d-4f43-be50-6548a82338dd

Storing in my...
✓ Stored in my: 61ea54fe-504d-4f43-be50-6548a82338dd

✅ Script completed successfully!
```

## 🎯 CLI Arguments

### `--instance` (or `-i`)

Define a predefined instance that will be available in your script.

**Format:** `name:url:db_id`

**Examples:**
```bash
# Single instance
--instance freezone:redis://localhost:6379:1

# Multiple instances
--instance freezone:redis://localhost:6379:1 \
--instance my:redis://localhost:6379:2 \
--instance production:redis://prod.example.com:6379:1

# Different hosts
--instance local:redis://localhost:6379:1 \
--instance remote:redis://remote.example.com:6379:1
```

**Parameters:**
- `name` - Instance name (will be available as a variable in scripts)
- `url` - HeroDB connection URL (redis://host:port)
- `db_id` - Database ID (0-15 typically)

## 📚 Use Cases

### 1. **Multi-Tenant Setup**

```bash
cargo run --bin runner --features rhai-support -- runner1 \
  --instance tenant1:redis://localhost:6379:1 \
  --instance tenant2:redis://localhost:6379:2 \
  --instance tenant3:redis://localhost:6379:3 \
  --script-file process_tenants.rhai
```

```rhai
// Script automatically has tenant1, tenant2, tenant3 available
tenant1.put_note(note1);
tenant2.put_note(note2);
tenant3.put_note(note3);
```

### 2. **Environment Separation**

```bash
cargo run --bin runner --features rhai-support -- runner1 \
  --instance dev:redis://dev:6379:1 \
  --instance staging:redis://staging:6379:1 \
  --instance prod:redis://prod:6379:1 \
  --script-file deploy.rhai
```

```rhai
// Test in dev first
dev.put_note(test_note);

// Then staging
staging.put_note(test_note);

// Finally production
prod.put_note(test_note);
```

### 3. **Data Migration**

```bash
cargo run --bin runner --features rhai-support -- runner1 \
  --instance source:redis://old-server:6379:1 \
  --instance target:redis://new-server:6379:1 \
  --script-file migrate.rhai
```

```rhai
// Migrate data from source to target
let ids = source.query("notes", "tags:tag", "migrate=true");
for id in ids {
    let note = source.get_note("notes", id);
    target.put_note(note);
}
```

### 4. **Freezone + Personal OSIRIS**

```bash
cargo run --bin runner --features rhai-support -- runner1 \
  --instance freezone:redis://freezone.io:6379:1 \
  --instance my:redis://localhost:6379:1 \
  --script-file sync.rhai
```

```rhai
// Your exact use case!
let my_note = note("notes")
    .title("Shared Note")
    .content("Available in both instances");

freezone.put_note(my_note);
my.put_note(my_note);
```

## 🏗️ Architecture

```
┌─────────────────────────────────────┐
│   CLI Arguments                     │
│   --instance freezone:redis:...:1   │
│   --instance my:redis:...:2         │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│   OsirisConfig                      │
│   Parse and validate instances      │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│   Engine + Scope                    │
│   Create instances and inject       │
│   into Rhai scope as constants      │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│   Rhai Script                       │
│   freezone.put_note(...)            │
│   my.put_note(...)                  │
└─────────────────────────────────────┘
```

## ✨ Features

### 1. **Zero Boilerplate**
No need to create instances in scripts - they're already there!

```rhai
// Before (manual creation)
let freezone = osiris("freezone", "redis://localhost:6379", 1);
let my = osiris("my", "redis://localhost:6379", 2);

// After (predefined)
// Just use them!
freezone.put_note(note);
my.put_note(note);
```

### 2. **Type Safety**
Instances are strongly typed and validated at startup.

### 3. **Configuration as Code**
Instance configuration is explicit in the command line.

### 4. **Multiple Instances**
Support unlimited predefined instances.

### 5. **Named Access**
Access instances by their meaningful names.

## 🔧 Advanced Usage

### Combining Predefined and Dynamic Instances

```bash
# Predefined instances
cargo run --bin runner --features rhai-support -- runner1 \
  --instance freezone:redis://localhost:6379:1 \
  --instance my:redis://localhost:6379:2 \
  --script-file script.rhai
```

```rhai
// Use predefined instances
freezone.put_note(note1);
my.put_note(note2);

// Create additional dynamic instances
let temp = osiris("temp", "redis://localhost:6379", 3);
temp.put_note(note3);
```

### Environment Variables

You can use environment variables in your shell:

```bash
export FREEZONE_URL="redis://freezone.io:6379"
export MY_URL="redis://localhost:6379"

cargo run --bin runner --features rhai-support -- runner1 \
  --instance freezone:${FREEZONE_URL}:1 \
  --instance my:${MY_URL}:1 \
  --script-file script.rhai
```

### Configuration File (Future Enhancement)

```toml
# osiris.toml
[instances]
freezone = { url = "redis://localhost:6379", db_id = 1 }
my = { url = "redis://localhost:6379", db_id = 2 }
```

```bash
cargo run --bin runner --features rhai-support -- runner1 \
  --config osiris.toml \
  --script-file script.rhai
```

## 💡 Best Practices

### 1. **Use Descriptive Names**
```bash
# Good
--instance production:redis://prod:6379:1
--instance staging:redis://staging:6379:1

# Less clear
--instance db1:redis://prod:6379:1
--instance db2:redis://staging:6379:1
```

### 2. **Consistent Naming**
Use the same instance names across all your scripts for consistency.

### 3. **Document Your Instances**
Add comments in your scripts explaining what each instance is for:

```rhai
// freezone: Public shared OSIRIS instance
// my: Personal local OSIRIS instance

freezone.put_note(public_note);
my.put_note(private_note);
```

### 4. **Separate Databases**
Use different database IDs for different purposes:

```bash
--instance notes:redis://localhost:6379:1 \
--instance events:redis://localhost:6379:2 \
--instance cache:redis://localhost:6379:3
```

## 🧪 Testing

### Test Script

```bash
cargo run --bin runner --features rhai-support -- test1 \
  --instance freezone:redis://localhost:6379:1 \
  --instance my:redis://localhost:6379:2 \
  --script-file scripts/predefined_instances.rhai
```

### Expected Output

```
✓ Instance: freezone → redis://localhost:6379 (DB 1)
✓ Instance: my → redis://localhost:6379 (DB 2)
✓ Stored in freezone: 61ea54fe-504d-4f43-be50-6548a82338dd
✓ Stored in my: 61ea54fe-504d-4f43-be50-6548a82338dd
✅ Script completed successfully!
```

## 🎉 Success!

Predefined instances are **fully operational** and ready for:
- ✅ Zero-boilerplate scripts
- ✅ Multi-tenant systems
- ✅ Environment separation
- ✅ Data migration
- ✅ Freezone + personal OSIRIS
- ✅ Production use

Your exact use case is now supported:
```bash
cargo run --bin runner --features rhai-support -- runner1 \
  --instance freezone:redis://freezone.io:6379:1 \
  --instance my:redis://localhost:6379:1 \
  --script-file my_script.rhai
```

```rhai
// Just use them!
freezone.put_note(my_note);
my.put_note(my_note);
```