nushell-plugins/nu_plugin_orchestrator/USAGE_EXAMPLES.md

# Orchestrator Plugin Usage Examples

This document provides comprehensive examples for using the `nu_plugin_orchestrator` plugin.

## Installation

First, register the plugin with Nushell:

```bash
# Build the plugin
cd provisioning/core/plugins/nushell-plugins/nu_plugin_orchestrator
cargo build --release

# Register with Nushell
plugin add target/release/nu_plugin_orchestrator
```

## Commands Overview

The plugin provides three main commands:

1. **`orch status`** - Get orchestrator status from local state
2. **`orch validate`** - Validate workflow KCL files
3. **`orch tasks`** - List orchestrator tasks from local queue

---

## 1. Checking Orchestrator Status

### Basic Status Check

```nushell
orch status
```

**Output:**
```
╭─────────────────┬────────────────────────────────────────────────────────╮
│ running         │ false                                                  │
│ tasks_pending   │ 5                                                      │
│ tasks_running   │ 2                                                      │
│ tasks_completed │ 10                                                     │
│ last_check      │ 2025-10-09T12:00:00Z                                  │
│ data_dir        │ provisioning/platform/orchestrator/data               │
╰─────────────────┴────────────────────────────────────────────────────────╯
```

### Custom Data Directory

```nushell
orch status --data-dir /custom/path/to/orchestrator/data
```

### Format as JSON

```nushell
orch status | to json
```

**Output:**
```json
{
  "running": false,
  "tasks_pending": 5,
  "tasks_running": 2,
  "tasks_completed": 10,
  "last_check": "2025-10-09T12:00:00Z",
  "data_dir": "provisioning/platform/orchestrator/data"
}
```

### Check if Orchestrator is Running

```nushell
if (orch status | get running) {
    print "Orchestrator is running"
} else {
    print "Orchestrator is not running"
}
```

---

## 2. Validating Workflow Files

### Basic Validation

```nushell
orch validate test-workflow.k
```

**Output (Valid):**
```
╭──────────┬──────╮
│ valid    │ true │
│ errors   │ []   │
│ warnings │ []   │
╰──────────┴──────╯
```

**Output (Invalid):**
```
╭──────────┬─────────────────────────────────────────────────────────────╮
│ valid    │ false                                                       │
│ errors   │ ["File not found: nonexistent.k"]                          │
│ warnings │ []                                                          │
╰──────────┴─────────────────────────────────────────────────────────────╯
```

### Strict Validation

Strict mode performs additional checks for required fields:

```nushell
orch validate workflow.k --strict
```

**Output:**
```
╭──────────┬──────────────────────────────────────────────────────────╮
│ valid    │ false                                                    │
│ errors   │ ["Missing 'operations' field (required)"]               │
│ warnings │ ["Missing 'name' field", "Missing 'version' field"]     │
╰──────────┴──────────────────────────────────────────────────────────╯
```

### Validation Pipeline

```nushell
# Validate and check if valid
orch validate workflow.k | if $in.valid {
    print "✓ Workflow is valid"
} else {
    print "✗ Workflow has errors"
}

# Validate multiple files
ls workflows/*.k | each { |file|
    let result = (orch validate $file.name)
    {
        file: $file.name,
        valid: $result.valid,
        error_count: ($result.errors | length)
    }
}
```

### Extract Validation Errors

```nushell
# Show only errors
orch validate workflow.k | get errors

# Show errors and warnings
let result = (orch validate workflow.k --strict)
print $"Errors: ($result.errors)"
print $"Warnings: ($result.warnings)"
```

---

## 3. Listing Tasks

### List All Tasks

```nushell
orch tasks
```

**Output:**
```
╭───┬──────────┬──────────┬──────────┬──────────────────────┬──────────────╮
│ # │    id    │  status  │ priority │     created_at       │ workflow_id  │
├───┼──────────┼──────────┼──────────┼──────────────────────┼──────────────┤
│ 0 │ task-001 │ pending  │       10 │ 2025-10-09T10:00:00Z │ workflow-123 │
│ 1 │ task-002 │ running  │        8 │ 2025-10-09T10:30:00Z │ workflow-123 │
│ 2 │ task-003 │ pending  │        5 │ 2025-10-09T11:00:00Z │              │
╰───┴──────────┴──────────┴──────────┴──────────────────────┴──────────────╯
```

### Filter by Status

```nushell
# Show only pending tasks
orch tasks --status pending

# Show only running tasks
orch tasks --status running

# Show only completed tasks
orch tasks --status completed
```

### Limit Results

```nushell
# Show only first 10 tasks
orch tasks --limit 10

# Show top 5 pending tasks
orch tasks --status pending --limit 5
```

### Combine Filters

```nushell
# Top 3 pending tasks
orch tasks --status pending --limit 3
```

### Task Analysis

```nushell
# Count tasks by status
orch tasks | group-by status | each { |key, items|
    {status: $key, count: ($items | length)}
}

# Find high-priority tasks
orch tasks | where priority > 7

# Tasks without workflow
orch tasks | where workflow_id == null

# Tasks created in last hour
orch tasks | where created_at > ((date now) - 1hr)
```

### Export to JSON

```nushell
# Export all tasks
orch tasks | to json > tasks.json

# Export pending tasks
orch tasks --status pending | to json > pending-tasks.json
```

---

## Advanced Usage Examples

### Monitoring Dashboard

```nushell
def orch-dashboard [] {
    let status = (orch status)
    let tasks = (orch tasks)

    print $"╭─────────────────────────────────────╮"
    print $"│  Orchestrator Dashboard            │"
    print $"╰─────────────────────────────────────╯"
    print ""
    print $"Status: ($status.running | if $in { '🟢 Running' } else { '🔴 Stopped' })"
    print $"Pending:   ($status.tasks_pending)"
    print $"Running:   ($status.tasks_running)"
    print $"Completed: ($status.tasks_completed)"
    print ""

    let by_status = ($tasks | group-by status | each { |key, items|
        {status: $key, count: ($items | length)}
    })

    print "Tasks by Status:"
    $by_status | table
}

orch-dashboard
```

### Validation Report

```nushell
def validate-all-workflows [] {
    ls workflows/*.k | each { |file|
        let result = (orch validate $file.name --strict)
        {
            file: ($file.name | path basename),
            valid: $result.valid,
            errors: ($result.errors | length),
            warnings: ($result.warnings | length)
        }
    } | table
}

validate-all-workflows
```

### Task Queue Monitor

```nushell
def monitor-queue [interval: duration = 5sec] {
    loop {
        clear
        print $"Last updated: (date now)"
        print ""
        orch tasks | table
        sleep $interval
    }
}

monitor-queue
```

### Automatic Workflow Validation

```nushell
def submit-workflow [workflow: string] {
    let validation = (orch validate $workflow --strict)

    if $validation.valid {
        print $"✓ Workflow ($workflow) is valid"
        # Submit to orchestrator
        # http post http://localhost:8080/workflows/batch/submit ...
    } else {
        print $"✗ Workflow ($workflow) has errors:"
        $validation.errors | each { |err| print $"  - ($err)" }
        error make {msg: "Workflow validation failed"}
    }
}

submit-workflow test-workflow.k
```

---

## Environment Variables

The plugin respects the following environment variables:

- **`ORCHESTRATOR_DATA_DIR`**: Override default data directory
  ```bash
  export ORCHESTRATOR_DATA_DIR=/custom/orchestrator/data
  orch status
  ```

---

## Data Directory Structure

The plugin expects the following directory structure:

```
provisioning/platform/orchestrator/data/
├── status.json                 # Orchestrator status
└── tasks/                      # Task queue
    ├── task-001.json
    ├── task-002.json
    └── task-003.json
```

### Status File Format (`status.json`)

```json
{
  "running": true,
  "tasks_pending": 5,
  "tasks_running": 2,
  "tasks_completed": 10,
  "last_check": "2025-10-09T12:00:00Z"
}
```

### Task File Format (`task-XXX.json`)

```json
{
  "id": "task-001",
  "status": "pending",
  "created_at": "2025-10-09T10:00:00Z",
  "priority": 10,
  "workflow_id": "workflow-123"
}
```

---

## Troubleshooting

### Plugin Not Found

If you get "command not found", ensure the plugin is registered:

```bash
plugin list | where name == nu_plugin_orchestrator
```

If not listed, register it:

```bash
plugin add target/release/nu_plugin_orchestrator
```

### Data Directory Not Found

If status.json or tasks directory doesn't exist, the plugin returns default values:

```nushell
orch status  # Returns default status with 0 tasks
orch tasks   # Returns empty list
```

Create the directory structure:

```bash
mkdir -p provisioning/platform/orchestrator/data/tasks
```

### KCL Validation Fails

Ensure `kcl` is in your PATH:

```bash
which kcl
kcl --version
```

---

## Integration Examples

### With CI/CD

```yaml
# .gitlab-ci.yml
validate-workflows:
  script:
    - nu -c "ls workflows/*.k | each { |f| orch validate $f.name --strict }"
```

### With Nushell Scripts

```nushell
# deploy.nu
use std assert

def main [workflow: string] {
    # Validate workflow
    let validation = (orch validate $workflow --strict)
    assert ($validation.valid) "Workflow validation failed"

    # Check orchestrator is running
    let status = (orch status)
    assert ($status.running) "Orchestrator is not running"

    # Submit workflow
    print "Submitting workflow..."
    # ... submit logic ...
}
```

---

## Performance Notes

- **`orch status`**: Reads single JSON file (~1ms)
- **`orch tasks`**: Walks task directory, O(n) for n tasks (~10ms for 1000 tasks)
- **`orch validate`**: Spawns `kcl` process (~50-100ms depending on workflow size)

---

## See Also

- [Orchestrator Architecture](/.claude/features/orchestrator-architecture.md)
- [Batch Workflow System](/.claude/features/batch-workflow-system.md)
- [KCL Idiomatic Patterns](/.claude/kcl_idiomatic_patterns.md)