# nu_plugin_tera

A powerful [Nushell](https://nushell.sh/) plugin for rendering [Tera templates](https://keats.github.io/tera/docs/) with structured data from Nushell pipelines.

## Overview

This plugin integrates Mozilla's Tera templating engine with Nushell, enabling you to generate dynamic content from structured data. Perfect for configuration files, documentation generation, reports, and any scenario where you need to combine templates with data.

## Installing

Clone this repository

> [!WARNING]
> **nu_plugin_tera** has dependencies to nushell source via local path in Cargo.toml
> Nushell and plugins require to be **sync** with same **version**

Clone [Nushell](https://nushell.sh/) alongside this plugin or change dependencies in [Cargo.toml](Cargo.toml)

This plugin is also included as submodule in [nushell-plugins](https://repo.jesusperez.pro/jesus/nushell-plugins)
as part of plugins collection for [Provisioning project](https://rlung.librecloud.online/jesus/provisioning)

Build from source

```nushell
> cd nu_plugin_tera
> cargo install --path .
```

### Nushell

In a [Nushell](https://nushell.sh/)

```nushell
> plugin add ~/.cargo/bin/nu_plugin_tera
```

## Commands

### `tera-render`

Render Tera templates with structured data from Nushell pipelines or arguments.

```nushell
> tera-render <template> [context]
```

**Parameters:**
- **template** `<path>`: Path to the `.tera` template file
- **context** `<any>`: Context data (record or JSON file path) (optional)

**Flags:**
- **-h**, **--help**: Display the help message for this command

## Template Syntax

Tera uses a Jinja2-inspired syntax with powerful features:

### Basic Variables
```jinja2
Hello, {{ name }}!
Your age is {{ age }}.
```

### Control Structures
```jinja2
{% if user.is_admin %}
  <p>Welcome, admin!</p>
{% else %}
  <p>Welcome, user!</p>
{% endif %}

{% for item in items %}
  - {{ item.name }}: {{ item.value }}
{% endfor %}
```

### Filters
```jinja2
{{ name | upper }}
{{ price | round(precision=2) }}
{{ date | date(format="%Y-%m-%d") }}
```

### Macros
```jinja2
{% macro render_field(name, value) %}
  <div class="field">
    <label>{{ name }}</label>
    <span>{{ value }}</span>
  </div>
{% endmacro %}

{{ render_field(name="Username", value=user.name) }}
```

## Usage Examples

### Basic Usage

**data.json**
```json
{
  "name": "Akasha",
  "projects": [
    {
      "name": "TheProject",
      "status": "active"
    },
    {
      "name": "AnotherProject",
      "status": "completed"
    }
  ]
}
```

**template.tera**
```jinja2
Hello, {{ name }}!

Projects:
{% for project in projects -%}
- {{ project.name }} ({{ project.status }})
{% endfor %}
```

**Rendering:**
```nushell
> open data.json | tera-render template.tera
Hello, Akasha!

Projects:
- TheProject (active)
- AnotherProject (completed)
```

### Pipeline Data Processing

```nushell
# Process system information
> sys | tera-render system-report.tera

# Generate configuration files from structured data
> {
    server: {
      host: "localhost",
      port: 8080,
      ssl: true
    },
    database: {
      host: "db.example.com",
      name: "myapp"
    }
  } | tera-render config.tera

# Process CSV data
> open employees.csv
  | tera-render employee-report.tera
```

### Multiple Data Sources

```nushell
# Using JSON file as context
> tera-render template.tera data.json

# Using record from pipeline
> { name: 'Akasha', projects: [ {'name': 'TheProject', 'status': 'active'} ] }
  | tera-render template.tera

# Wrapping data for template access
> open data.json | wrap value | tera-render template.tera
```

## Advanced Templates

### Configuration File Generation

**nginx.conf.tera**
```jinja2
server {
    listen {{ server.port }}{% if server.ssl %} ssl{% endif %};
    server_name {{ server.host }};

    {% if server.ssl %}
    ssl_certificate {{ ssl.cert_path }};
    ssl_certificate_key {{ ssl.key_path }};
    {% endif %}

    {% for location in locations %}
    location {{ location.path }} {
        proxy_pass {{ location.upstream }};
        {% for header in location.headers | default(value=[]) %}
        proxy_set_header {{ header.name }} {{ header.value }};
        {% endfor %}
    }
    {% endfor %}
}
```

**Usage:**
```nushell
> {
    server: {
      host: "example.com",
      port: 443,
      ssl: true
    },
    ssl: {
      cert_path: "/etc/ssl/cert.pem",
      key_path: "/etc/ssl/key.pem"
    },
    locations: [
      {
        path: "/api/",
        upstream: "http://backend:8080",
        headers: [
          {name: "Host", value: "$host"},
          {name: "X-Real-IP", value: "$remote_addr"}
        ]
      }
    ]
  } | tera-render nginx.conf.tera | save nginx.conf
```

### Documentation Generation

**api-docs.md.tera**
```jinja2
# {{ api.title }} API Documentation

Version: {{ api.version }}
Last updated: {{ "now" | date(format="%Y-%m-%d") }}

## Endpoints

{% for endpoint in api.endpoints %}
### {{ endpoint.method | upper }} {{ endpoint.path }}

{{ endpoint.description }}

{% if endpoint.parameters %}
**Parameters:**
{% for param in endpoint.parameters %}
- `{{ param.name }}` ({{ param.type }}){% if param.required %} *required*{% endif %}: {{ param.description }}
{% endfor %}
{% endif %}

**Example Response:**
```json
{{ endpoint.example_response | tojson }}
```

---
{% endfor %}
```

### Report Generation

```nushell
# Generate system report
def generate-system-report [] {
    let data = {
        timestamp: (date now | format date "%Y-%m-%d %H:%M:%S"),
        system: (sys),
        processes: (ps | first 10),
        disk_usage: (df)
    }

    $data | tera-render system-report.html.tera | save $"reports/system-report-(date now | format date "%Y%m%d").html"
}

# Generate project status report
def generate-project-report [project_dir: string] {
    let data = {
        project: (open $"($project_dir)/package.json" | get name),
        files: (ls $project_dir | length),
        git_status: (git -C $project_dir status --porcelain | lines),
        last_commit: (git -C $project_dir log -1 --format="%h %s %an %ad" --date=short)
    }

    $data | tera-render project-report.md.tera
}
```

## Workflow Examples

### CI/CD Pipeline Configuration

```nushell
# Generate Kubernetes manifests
def generate-k8s-manifests [env: string] {
    let config = (open $"configs/($env).json")

    [
        "deployment.yaml.tera",
        "service.yaml.tera",
        "ingress.yaml.tera"
    ] | each { |template|
        let output = ($config | tera-render $"templates/($template)")
        $output | save $"manifests/($env)/(($template | str replace '.tera' ''))"
    }
}

# Generate environment-specific configs
def generate-env-configs [] {
    ["dev", "staging", "prod"] | each { |env|
        let base_config = (open base-config.json)
        let env_config = (open $"($env)-config.json")
        let merged = ($base_config | merge $env_config)

        $merged | tera-render app-config.yaml.tera | save $"configs/($env).yaml"
    }
}
```

### Content Management

```nushell
# Generate blog posts from structured data
def generate-blog-posts [] {
    ls content/*.json
    | each { |post_file|
        let post_data = (open $post_file.name)
        let filename = ($post_file.name | path basename | str replace '.json' '.html')

        $post_data | tera-render blog-post.html.tera | save $"output/($filename)"
    }
}

# Generate navigation menus
def generate-navigation [site_config: string] {
    open $site_config
    | get pages
    | tera-render navigation.html.tera
    | save includes/navigation.html
}
```

### Infrastructure as Code

```nushell
# Generate Terraform configurations
def generate-terraform [environment: string] {
    let vars = (open $"terraform/($environment).tfvars.json")

    ls terraform/templates/*.tf.tera
    | each { |template|
        let output_name = ($template.name | path basename | str replace '.tera' '')
        $vars | tera-render $template.name | save $"terraform/($environment)/($output_name)"
    }
}

# Generate Docker Compose files
def generate-docker-compose [services: list] {
    let compose_data = {
        services: $services,
        networks: ["app-network"],
        volumes: ["db-data", "app-logs"]
    }

    $compose_data | tera-render docker-compose.yml.tera | save docker-compose.yml
}
```

## Integration with Nushell Data Processing

Leverage Nushell's powerful data manipulation with Tera templating:

```nushell
# Process and template CSV data
> open sales.csv
  | group-by region
  | transpose region sales
  | insert total { |row| $row.sales | math sum }
  | tera-render sales-report.html.tera
  | save reports/sales-summary.html

# Combine multiple data sources
> let weather = (http get "https://api.weather.com/current")
> let system = (sys)
> {weather: $weather, system: $system}
  | tera-render dashboard.html.tera

# Batch process templates
> ls templates/*.tera
  | each { |template|
      let data = (open $"data/(($template.name | path basename | str replace '.tera' '.json'))")
      $data | tera-render $template.name
    }
```

## Error Handling

The plugin provides detailed error messages for common issues:

```nushell
# Template syntax errors
> {} | tera-render broken-template.tera
Error: Template error
  ╭─[calling tera-render]
  │ Template parse error: Unexpected token...

# Missing variables
> {} | tera-render template-with-vars.tera
Error: Render error
  ╭─[calling tera-render]
  │ Variable 'name' not found in context

# File not found
> {} | tera-render nonexistent.tera
Error: Read error
  ╭─[calling tera-render]
  │ Failed to read file 'nonexistent.tera': No such file...
```

## Features

- ✅ **Pipeline Integration** - Seamlessly process Nushell data structures
- ✅ **Multiple Data Sources** - Support for JSON files, records, and pipeline data
- ✅ **Rich Template Syntax** - Full Tera templating features (filters, macros, inheritance)
- ✅ **Error Handling** - Detailed error messages with context
- ✅ **File I/O** - Read templates from files, save rendered output
- ✅ **Data Wrapping** - Automatic handling of different data structures
- ✅ **Performance** - Efficient template compilation and rendering

## Use Cases

- **Configuration Management**: Generate environment-specific config files
- **Documentation**: Create dynamic documentation from structured data
- **Infrastructure as Code**: Template Terraform, Kubernetes, Docker configurations
- **Reports**: Generate HTML/Markdown reports from system data
- **Web Development**: Template generation for static sites
- **CI/CD**: Dynamic pipeline configurations
- **Content Management**: Blog posts, newsletters, and content generation
- **Monitoring**: Dashboard and alert template generation

## Template Best Practices

### 1. Organize Templates
```
templates/
├── base.html.tera          # Base layouts
├── components/
│   ├── header.html.tera    # Reusable components
│   └── footer.html.tera
├── pages/
│   ├── home.html.tera      # Page templates
│   └── about.html.tera
└── configs/
    ├── nginx.conf.tera     # Configuration templates
    └── docker.yml.tera
```

### 2. Use Template Inheritance
**base.html.tera**
```jinja2
<!DOCTYPE html>
<html>
<head>
    <title>{% block title %}{{ site.title }}{% endblock %}</title>
</head>
<body>
    {% block content %}{% endblock %}
</body>
</html>
```

**page.html.tera**
```jinja2
{% extends "base.html.tera" %}

{% block title %}{{ page.title }} - {{ site.title }}{% endblock %}

{% block content %}
    <h1>{{ page.title }}</h1>
    {{ page.content }}
{% endblock %}
```

### 3. Create Reusable Functions
```nushell
# Template rendering helper
def render-template [template: string, data: any] {
    $data | tera-render $template
}

# Batch template processing
def render-all-templates [data_dir: string, template_dir: string, output_dir: string] {
    ls $"($data_dir)/*.json"
    | each { |data_file|
        let basename = ($data_file.name | path basename | str replace '.json' '')
        let template = $"($template_dir)/($basename).tera"
        let output = $"($output_dir)/($basename).html"

        if ($template | path exists) {
            open $data_file.name | tera-render $template | save $output
            print $"Generated: ($output)"
        }
    }
}
```

## Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

## License

This project is licensed under the MIT License.

## Related Projects

- [Tera](https://keats.github.io/tera/) - Template engine for Rust
- [Nushell](https://nushell.sh/) - A new type of shell
- [nu_plugin_fluent](../nu_plugin_fluent/) - Fluent localization plugin for Nushell