nushell-plugins/nu_plugin_orchestrator/usage-examples.md

# Orchestrator Plugin Usage Examples\n\nThis document provides comprehensive examples for using the `nu_plugin_orchestrator` plugin.\n\n## Installation\n\nFirst, register the plugin with Nushell:\n\n```bash\n# Build the plugin\ncd provisioning/core/plugins/nushell-plugins/nu_plugin_orchestrator\ncargo build --release\n\n# Register with Nushell\nplugin add target/release/nu_plugin_orchestrator\n```\n\n## Commands Overview\n\nThe plugin provides three main commands:\n\n1. **`orch status`** - Get orchestrator status from local state\n2. **`orch validate`** - Validate workflow KCL files\n3. **`orch tasks`** - List orchestrator tasks from local queue\n\n---\n\n## 1. Checking Orchestrator Status\n\n### Basic Status Check\n\n```nushell\norch status\n```\n\n**Output:**\n\n```plaintext\n╭─────────────────┬────────────────────────────────────────────────────────╮\n│ running         │ false                                                  │\n│ tasks_pending   │ 5                                                      │\n│ tasks_running   │ 2                                                      │\n│ tasks_completed │ 10                                                     │\n│ last_check      │ 2025-10-09T12:00:00Z                                  │\n│ data_dir        │ provisioning/platform/orchestrator/data               │\n╰─────────────────┴────────────────────────────────────────────────────────╯\n```\n\n### Custom Data Directory\n\n```nushell\norch status --data-dir /custom/path/to/orchestrator/data\n```\n\n### Format as JSON\n\n```nushell\norch status | to json\n```\n\n**Output:**\n\n```json\n{\n  "running": false,\n  "tasks_pending": 5,\n  "tasks_running": 2,\n  "tasks_completed": 10,\n  "last_check": "2025-10-09T12:00:00Z",\n  "data_dir": "provisioning/platform/orchestrator/data"\n}\n```\n\n### Check if Orchestrator is Running\n\n```nushell\nif (orch status | get running) {\n    print "Orchestrator is running"\n} else {\n    print "Orchestrator is not running"\n}\n```\n\n---\n\n## 2. Validating Workflow Files\n\n### Basic Validation\n\n```nushell\norch validate test-workflow.k\n```\n\n**Output (Valid):**\n\n```plaintext\n╭──────────┬──────╮\n│ valid    │ true │\n│ errors   │ []   │\n│ warnings │ []   │\n╰──────────┴──────╯\n```\n\n**Output (Invalid):**\n\n```plaintext\n╭──────────┬─────────────────────────────────────────────────────────────╮\n│ valid    │ false                                                       │\n│ errors   │ ["File not found: nonexistent.k"]                          │\n│ warnings │ []                                                          │\n╰──────────┴─────────────────────────────────────────────────────────────╯\n```\n\n### Strict Validation\n\nStrict mode performs additional checks for required fields:\n\n```nushell\norch validate workflow.k --strict\n```\n\n**Output:**\n\n```plaintext\n╭──────────┬──────────────────────────────────────────────────────────╮\n│ valid    │ false                                                    │\n│ errors   │ ["Missing 'operations' field (required)"]               │\n│ warnings │ ["Missing 'name' field", "Missing 'version' field"]     │\n╰──────────┴──────────────────────────────────────────────────────────╯\n```\n\n### Validation Pipeline\n\n```nushell\n# Validate and check if valid\norch validate workflow.k | if $in.valid {\n    print "✓ Workflow is valid"\n} else {\n    print "✗ Workflow has errors"\n}\n\n# Validate multiple files\nls workflows/*.k | each { |file|\n    let result = (orch validate $file.name)\n    {\n        file: $file.name,\n        valid: $result.valid,\n        error_count: ($result.errors | length)\n    }\n}\n```\n\n### Extract Validation Errors\n\n```nushell\n# Show only errors\norch validate workflow.k | get errors\n\n# Show errors and warnings\nlet result = (orch validate workflow.k --strict)\nprint $"Errors: ($result.errors)"\nprint $"Warnings: ($result.warnings)"\n```\n\n---\n\n## 3. Listing Tasks\n\n### List All Tasks\n\n```nushell\norch tasks\n```\n\n**Output:**\n\n```plaintext\n╭───┬──────────┬──────────┬──────────┬──────────────────────┬──────────────╮\n│ # │    id    │  status  │ priority │     created_at       │ workflow_id  │\n├───┼──────────┼──────────┼──────────┼──────────────────────┼──────────────┤\n│ 0 │ task-001 │ pending  │       10 │ 2025-10-09T10:00:00Z │ workflow-123 │\n│ 1 │ task-002 │ running  │        8 │ 2025-10-09T10:30:00Z │ workflow-123 │\n│ 2 │ task-003 │ pending  │        5 │ 2025-10-09T11:00:00Z │              │\n╰───┴──────────┴──────────┴──────────┴──────────────────────┴──────────────╯\n```\n\n### Filter by Status\n\n```nushell\n# Show only pending tasks\norch tasks --status pending\n\n# Show only running tasks\norch tasks --status running\n\n# Show only completed tasks\norch tasks --status completed\n```\n\n### Limit Results\n\n```nushell\n# Show only first 10 tasks\norch tasks --limit 10\n\n# Show top 5 pending tasks\norch tasks --status pending --limit 5\n```\n\n### Combine Filters\n\n```nushell\n# Top 3 pending tasks\norch tasks --status pending --limit 3\n```\n\n### Task Analysis\n\n```nushell\n# Count tasks by status\norch tasks | group-by status | each { |key, items|\n    {status: $key, count: ($items | length)}\n}\n\n# Find high-priority tasks\norch tasks | where priority > 7\n\n# Tasks without workflow\norch tasks | where workflow_id == null\n\n# Tasks created in last hour\norch tasks | where created_at > ((date now) - 1hr)\n```\n\n### Export to JSON\n\n```nushell\n# Export all tasks\norch tasks | to json > tasks.json\n\n# Export pending tasks\norch tasks --status pending | to json > pending-tasks.json\n```\n\n---\n\n## Advanced Usage Examples\n\n### Monitoring Dashboard\n\n```nushell\ndef orch-dashboard [] {\n    let status = (orch status)\n    let tasks = (orch tasks)\n\n    print $"╭─────────────────────────────────────╮"\n    print $"│  Orchestrator Dashboard            │"\n    print $"╰─────────────────────────────────────╯"\n    print ""\n    print $"Status: ($status.running | if $in { '🟢 Running' } else { '🔴 Stopped' })"\n    print $"Pending:   ($status.tasks_pending)"\n    print $"Running:   ($status.tasks_running)"\n    print $"Completed: ($status.tasks_completed)"\n    print ""\n\n    let by_status = ($tasks | group-by status | each { |key, items|\n        {status: $key, count: ($items | length)}\n    })\n\n    print "Tasks by Status:"\n    $by_status | table\n}\n\norch-dashboard\n```\n\n### Validation Report\n\n```nushell\ndef validate-all-workflows [] {\n    ls workflows/*.k | each { |file|\n        let result = (orch validate $file.name --strict)\n        {\n            file: ($file.name | path basename),\n            valid: $result.valid,\n            errors: ($result.errors | length),\n            warnings: ($result.warnings | length)\n        }\n    } | table\n}\n\nvalidate-all-workflows\n```\n\n### Task Queue Monitor\n\n```nushell\ndef monitor-queue [interval: duration = 5sec] {\n    loop {\n        clear\n        print $"Last updated: (date now)"\n        print ""\n        orch tasks | table\n        sleep $interval\n    }\n}\n\nmonitor-queue\n```\n\n### Automatic Workflow Validation\n\n```nushell\ndef submit-workflow [workflow: string] {\n    let validation = (orch validate $workflow --strict)\n\n    if $validation.valid {\n        print $"✓ Workflow ($workflow) is valid"\n        # Submit to orchestrator\n        # http post http://localhost:8080/workflows/batch/submit ...\n    } else {\n        print $"✗ Workflow ($workflow) has errors:"\n        $validation.errors | each { |err| print $"  - ($err)" }\n        error make {msg: "Workflow validation failed"}\n    }\n}\n\nsubmit-workflow test-workflow.k\n```\n\n---\n\n## Environment Variables\n\nThe plugin respects the following environment variables:\n\n- **`ORCHESTRATOR_DATA_DIR`**: Override default data directory\n\n  ```bash\n  export ORCHESTRATOR_DATA_DIR=/custom/orchestrator/data\n  orch status\n  ```\n\n---\n\n## Data Directory Structure\n\nThe plugin expects the following directory structure:\n\n```plaintext\nprovisioning/platform/orchestrator/data/\n├── status.json                 # Orchestrator status\n└── tasks/                      # Task queue\n    ├── task-001.json\n    ├── task-002.json\n    └── task-003.json\n```\n\n### Status File Format (`status.json`)\n\n```json\n{\n  "running": true,\n  "tasks_pending": 5,\n  "tasks_running": 2,\n  "tasks_completed": 10,\n  "last_check": "2025-10-09T12:00:00Z"\n}\n```\n\n### Task File Format (`task-XXX.json`)\n\n```json\n{\n  "id": "task-001",\n  "status": "pending",\n  "created_at": "2025-10-09T10:00:00Z",\n  "priority": 10,\n  "workflow_id": "workflow-123"\n}\n```\n\n---\n\n## Troubleshooting\n\n### Plugin Not Found\n\nIf you get "command not found", ensure the plugin is registered:\n\n```bash\nplugin list | where name == nu_plugin_orchestrator\n```\n\nIf not listed, register it:\n\n```bash\nplugin add target/release/nu_plugin_orchestrator\n```\n\n### Data Directory Not Found\n\nIf status.json or tasks directory doesn't exist, the plugin returns default values:\n\n```nushell\norch status  # Returns default status with 0 tasks\norch tasks   # Returns empty list\n```\n\nCreate the directory structure:\n\n```bash\nmkdir -p provisioning/platform/orchestrator/data/tasks\n```\n\n### KCL Validation Fails\n\nEnsure `kcl` is in your PATH:\n\n```bash\nwhich kcl\nkcl --version\n```\n\n---\n\n## Integration Examples\n\n### With CI/CD\n\n```yaml\n# .gitlab-ci.yml\nvalidate-workflows:\n  script:\n    - nu -c "ls workflows/*.k | each { |f| orch validate $f.name --strict }"\n```\n\n### With Nushell Scripts\n\n```nushell\n# deploy.nu\nuse std assert\n\ndef main [workflow: string] {\n    # Validate workflow\n    let validation = (orch validate $workflow --strict)\n    assert ($validation.valid) "Workflow validation failed"\n\n    # Check orchestrator is running\n    let status = (orch status)\n    assert ($status.running) "Orchestrator is not running"\n\n    # Submit workflow\n    print "Submitting workflow..."\n    # ... submit logic ...\n}\n```\n\n---\n\n## Performance Notes\n\n- **`orch status`**: Reads single JSON file (~1ms)\n- **`orch tasks`**: Walks task directory, O(n) for n tasks (~10ms for 1000 tasks)\n- **`orch validate`**: Spawns `kcl` process (~50-100ms depending on workflow size)\n\n---\n\n## See Also\n\n- [Orchestrator Architecture](/.claude/features/orchestrator-architecture.md)\n- [Batch Workflow System](/.claude/features/batch-workflow-system.md)\n- [KCL Idiomatic Patterns](/.claude/kcl_idiomatic_patterns.md)