# Nushell Plugins

Provisioning includes 17 high-performance native Rust plugins for Nushell, providing 10-50x
speed improvements over HTTP APIs. Plugins handle critical functionality: templates, configuration,
encryption, orchestration, and secrets management.

## Overview

### Performance Benefits

Plugins provide significant performance improvements for frequently-used operations:

| Plugin | Speed Improvement | Use Case |
| --- | --- | --- |
| **nu_plugin_tera** | 10-15x faster | Template rendering |
| **nu_plugin_nickel** | 5-8x faster | Configuration processing |
| **nu_plugin_orchestrator** | 30-50x faster | Query orchestrator state |
| **nu_plugin_kms** | 10x faster | Encryption/decryption |
| **nu_plugin_auth** | 5x faster | Authentication operations |

### Installation

All plugins install automatically with Provisioning:

```bash
# Automatic installation during setup
provisioning install

# Or manual installation
cd /path/to/provisioning
./scripts/install-plugins.nu

# Verify installation
provisioning plugins list
```

### Plugin Management

```bash
# List installed plugins with versions
provisioning plugins list

# Check plugin status
provisioning plugins status

# Update all plugins
provisioning plugins update --all

# Update specific plugin
provisioning plugins update nu_plugin_tera

# Remove plugin
provisioning plugins remove nu_plugin_tera
```

## Core Plugins (Priority)

### 1. nu_plugin_tera

**Template Rendering Engine**

Nushell plugin for Tera template processing (Jinja2-style syntax).

```bash
# Install
provisioning plugins install nu_plugin_tera

# Usage in Nushell
let template = "Hello {{ name }}!"
let context = { name: "World" }
$template | tera render $context
# Output: "Hello World!"
```

**Features**:

- Jinja2-compatible syntax
- Built-in filters and functions
- Template inheritance
- Macro support
- Custom filters via Rust

**Performance**: 10-15x faster than HTTP template service

**Use Cases**:

- Generating infrastructure configurations
- Creating dynamic scripts
- Building deployment templates
- Rendering documentation

**Example: Generate infrastructure config**:

```nushell
let infra_template = "
{
  servers = [
    {% for server in servers %}
    {
      name = \"{{ server.name }}\"
      cpu = {{ server.cpu }}
      memory = {{ server.memory }}
    }
    {% if not loop.last %},{% endif %}
    {% endfor %}
  ]
}
"

let servers = [
  { name: "web-01", cpu: 4, memory: 8 }
  { name: "web-02", cpu: 4, memory: 8 }
]

$infra_template | tera render { servers: $servers }
```

---

### 2. nu_plugin_nickel

**Nickel Configuration Plugin**

Native Nickel compilation and validation in Nushell.

```bash
# Install
provisioning plugins install nu_plugin_nickel

# Usage in Nushell
let nickel_code = '{ name = "server", cpu = 4 }'
$nickel_code | nickel eval
# Output: { name: "server", cpu: 4 }
```

**Features**:

- Parse and evaluate Nickel expressions
- Type checking and validation
- Schema enforcement
- Merge configurations
- Generate JSON/YAML output

**Performance**: 5-8x faster than CLI invocation

**Use Cases**:

- Validate infrastructure definitions
- Process Nickel schemas
- Merge configuration files
- Generate typed configurations

**Example: Validate and merge configs**:

```nushell
let base_config = open base.ncl | nickel eval
let env_config = open prod-defaults.ncl | nickel eval

let merged = $base_config | nickel merge $env_config
$merged | nickel validate --schema infrastructure-schema.ncl
```

---

### 3. nu_plugin_fluent

**Internationalization (i18n) Plugin**

Fluent translation system for multi-language support.

```bash
# Install
provisioning plugins install nu_plugin_fluent

# Usage in Nushell
fluent load "./locales"
fluent set-locale "es-ES"
fluent get "help-infra-server-create"
# Output: "Crear un nuevo servidor"
```

**Features**:

- Load Fluent catalogs (.ftl files)
- Dynamic locale switching
- Pluralization support
- Fallback chains
- Translation coverage reports

**Performance**: Native Rust implementation, <1ms per translation

**Use Cases**:

- CLI help text in multiple languages
- Form labels and prompts
- Error messages
- Interactive guides

**Supported Locales**:

- en-US (English)
- es-ES (Spanish)
- pt-BR (Portuguese - planned)
- fr-FR (French - planned)
- ja-JP (Japanese - planned)

**Example: Multi-language help system**:

```nushell
fluent load "provisioning/locales"

# Spanish help
fluent set-locale "es-ES"
fluent get "help-main-title"    # "SISTEMA DE PROVISIÓN"

# English help (fallback)
fluent set-locale "fr-FR"
fluent get "help-main-title"    # Falls back to "PROVISIONING SYSTEM"
```

---

### 4. nu_plugin_secretumvault

**Post-Quantum Cryptography Vault**

SecretumVault integration for quantum-resistant secret storage.

```bash
# Install
provisioning plugins install nu_plugin_secretumvault

# Usage in Nushell
secretumvault-plugin store "api-key" "secret-value"
let key = secretumvault-plugin retrieve "api-key"
secretumvault-plugin delete "api-key"
```

**Features**:

- CRYSTALS-Kyber encryption (post-quantum)
- Hybrid encryption (PQC + AES-256)
- Secure credential injection
- Key rotation
- Audit logging

**Performance**: <100ms for encrypt/decrypt operations

**Use Cases**:

- Store infrastructure credentials
- Manage API keys
- Handle database passwords
- Secure configuration values

**Example: Secure credential management**:

```nushell
# Store credentials in vault
secretumvault-plugin store "aws-access-key" "AKIAIOSFODNN7EXAMPLE"
secretumvault-plugin store "aws-secret-key" "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

# Retrieve for use
let aws_key = secretumvault-plugin retrieve "aws-access-key"
provisioning aws configure --access-key $aws_key
```

---

## Performance Plugins

### 5. nu_plugin_orchestrator

**Orchestrator State Query Plugin**

High-speed queries to orchestrator state and workflow data.

```bash
# Install
provisioning plugins install nu_plugin_orchestrator

# Usage in Nushell
orchestrator query workflows --filter status=running
orchestrator query tasks --limit 100
orchestrator query checkpoints --workflow deploy-k8s
```

**Performance**: 30-50x faster than HTTP API

**Queries**:

- Workflows (list, status, logs)
- Tasks (state, duration, dependencies)
- Checkpoints (recovery points)
- History (audit trail)

**Example: Monitor running workflows**:

```nushell
let running = orchestrator query workflows --filter status=running
$running | each { | w |
  print $"Workflow: ($w.name) - ($w.progress)%"
}
```

---

### 6. nu_plugin_kms

**Key Management System (Encryption) Plugin**

Fast encryption/decryption with KMS backends.

```bash
# Install
provisioning plugins install nu_plugin_kms

# Usage in Nushell
let encrypted = "secret-data" | kms encrypt --algorithm aes-256-gcm
$encrypted | kms decrypt
```

**Performance**: 10x faster than external KMS calls, 5ms encryption

**Supported Algorithms**:

- AES-256-GCM
- ChaCha20-Poly1305
- Kyber (post-quantum)
- Falcon (signatures)

**Features**:

- Symmetric encryption
- Key derivation (Argon2id, PBKDF2)
- Authenticated encryption
- HSM integration (optional)

**Example: Encrypt infrastructure secrets**:

```nushell
let config = open infrastructure.ncl
let encrypted = $config | kms encrypt --key master-key

# Decrypt when needed
let decrypted = $encrypted | kms decrypt --key master-key
$decrypted | nickel eval
```

---

### 7. nu_plugin_auth

**Authentication Plugin**

Multi-method authentication with keyring integration.

```bash
# Install
provisioning plugins install nu_plugin_auth

# Usage in Nushell
let token = auth login --method jwt --provider openid
auth set-token $token
auth verify-token
```

**Performance**: 5x faster local authentication

**Features**:

- JWT token generation and validation
- OAuth2 support
- SAML support
- OS keyring integration
- MFA support

**Methods**:

- JWT (JSON Web Tokens)
- OAuth2 (GitHub, Google, Microsoft)
- SAML
- LDAP
- Local keyring

**Example: Authenticate and store credentials**:

```nushell
# Login and get token
let token = auth login --method oauth2 --provider github
auth set-token $token --store-keyring

# Verify authentication
auth verify-token      # Check if token valid
auth whoami            # Show current user
```

---

## Utility Plugins

### 8. nu_plugin_hashes

**Cryptographic Hashing Plugin**

Multiple hash algorithms for data integrity.

```bash
# Install
provisioning plugins install nu_plugin_hashes

# Usage in Nushell
"data" | hashes sha256
"data" | hashes blake3
```

**Algorithms**:

- SHA256, SHA512
- BLAKE3
- MD5 (legacy)
- SHA1 (legacy)

---

### 9. nu_plugin_highlight

**Syntax Highlighting Plugin**

Code syntax highlighting for display and logging.

```bash
# Install
provisioning plugins install nu_plugin_highlight

# Usage in Nushell
open script.sh | highlight --language bash
open config.ncl | highlight --language nickel
```

**Languages**:

- Bash/Shell
- Nickel
- YAML
- JSON
- Rust
- SQL
- Others

---

### 10. nu_plugin_image

**Image Processing Plugin**

Image manipulation and format conversion.

```bash
# Install
provisioning plugins install nu_plugin_image

# Usage in Nushell
open diagram.png | image resize --width 800 --height 600
open logo.jpg | image convert --format webp
```

**Operations**:

- Resize, crop, rotate
- Format conversion
- Compression
- Metadata extraction

---

### 11. nu_plugin_clipboard

**Clipboard Management Plugin**

Read/write system clipboard.

```bash
# Install
provisioning plugins install nu_plugin_clipboard

# Usage in Nushell
"api-key" | clipboard copy
clipboard paste
```

**Features**:

- Copy to clipboard
- Paste from clipboard
- Manage clipboard history
- Cross-platform support

---

### 12. nu_plugin_desktop_notifications

**Desktop Notifications Plugin**

System notifications for long-running operations.

```bash
# Install
provisioning plugins install nu_plugin_desktop_notifications

# Usage in Nushell
notifications notify "Deployment completed" --type success
notifications notify "Errors detected" --type error
```

**Features**:

- Success, warning, error notifications
- Custom titles and messages
- Sound alerts

---

### 13. nu_plugin_qr_maker

**QR Code Generator Plugin**

Generate QR codes for configuration sharing.

```bash
# Install
provisioning plugins install nu_plugin_qr_maker

# Usage in Nushell
" [https://example.com/config"](https://example.com/config") | qr-maker generate --output config.png
"workspace-setup-command" | qr-maker generate --ascii
```

---

### 14. nu_plugin_port_extension

**Port/Network Utilities Plugin**

Network port management and diagnostics.

```bash
# Install
provisioning plugins install nu_plugin_port_extension

# Usage in Nushell
port-extension list-open --port 8080
port-extension check-available --port 9000
```

---

## Legacy/Secondary Plugins

### 15. nu_plugin_kcl

**KCL Configuration Plugin (DEPRECATED)**

Legacy KCL support (Nickel is preferred).

⚠️ **Status**: Deprecated - Use nu_plugin_nickel instead

```bash
# Install
provisioning plugins install nu_plugin_kcl

# Usage (not recommended)
let config = open config.kcl | kcl eval
```

---

### 16. api_nu_plugin_kcl

**KCL API Plugin (DEPRECATED)**

HTTP API wrapper for KCL.

⚠️ **Status**: Deprecated - Use nu_plugin_nickel instead

---

### 17. _nu_plugin_inquire (Historical)

**Interactive Prompts Plugin (HISTORICAL)**

Old inquiry/prompt system, replaced by TypeDialog.

⚠️ **Status**: Historical/archived

---

## Plugin Installation & Management

### Installation Methods

**Automatic with Provisioning**:

```bash
provisioning install
# Installs all recommended plugins automatically
```

**Selective Installation**:

```bash
# Install specific plugins
provisioning plugins install nu_plugin_tera nu_plugin_nickel nu_plugin_secretumvault

# Install plugin category
provisioning plugins install --category core          # Essential plugins
provisioning plugins install --category performance   # Performance plugins
provisioning plugins install --category utilities     # Utility plugins
```

**Manual Installation**:

```bash
# Build and install from source
cd /Users/Akasha/project-provisioning/plugins/nushell-plugins/nu_plugin_tera
cargo install --path .

# Then load in Nushell
plugin add nu_plugin_tera
```

### Configuration

**Plugin Loading in Nushell**:

```nushell
# In env.nu or config.nu
plugin add nu_plugin_tera
plugin add nu_plugin_nickel
plugin add nu_plugin_secretumvault
plugin add nu_plugin_fluent
plugin add nu_plugin_auth
plugin add nu_plugin_kms
plugin add nu_plugin_orchestrator

# And more...
```

**Plugin Status**:

```bash
# Check all plugins
provisioning plugins list

# Check specific plugin
provisioning plugins status nu_plugin_tera

# Detailed information
provisioning plugins info nu_plugin_tera --verbose
```

## Best Practices

### Use Plugins When

- ✅ Processing large amounts of data (templates, config)
- ✅ Sensitive operations (encryption, secrets)
- ✅ Frequent operations (queries, auth)
- ✅ Performance critical paths

### Fallback to HTTP API When

- ❌ Plugin not installed (automatic fallback)
- ❌ Older Nushell version incompatible
- ❌ Special features only in API

```nushell
# Plugins have automatic fallback
# If nu_plugin_tera not available, uses HTTP API automatically
let template = "{{ name }}" | tera render { name: "test" }
# Works either way
```

## Troubleshooting

### Plugin Not Loading

```bash
# Reload Nushell
nu

# Check plugin errors
plugin list --debug

# Reinstall plugin
provisioning plugins remove nu_plugin_tera
provisioning plugins install nu_plugin_tera
```

### Performance Issues

```bash
# Check plugin status
provisioning plugins status

# Monitor plugin usage
provisioning monitor plugins

# Profile plugin calls
provisioning profile nu_plugin_tera
```

## Related Documentation

- [Features Overview](./README.md) - Feature list
- [Nushell Libraries](../api-reference/nushell-libraries.md) - Core libraries
- [CLI Architecture](./cli-architecture.md) - Command dispatch
- [Performance Optimization](../operations/monitoring.md) - Monitoring
