nushell-plugins/guides/DISTRIBUTION_INSTALLER_WORKFLOW.md

# Nushell Plugin Distribution Installer Workflow

Complete workflow for creating and distributing Nushell plugins with manifest-based installation.

## Overview

The distribution installer system has three main components:

1. **Manifest Generator** - Scans plugins and creates a manifest
2. **Manifest File** - JSON file listing all available plugins
3. **Distribution Installer** - Lets users choose which plugins to install/register

## Workflow

### Step 1: Create Distribution Manifest

When you're packaging the distribution:

```bash
# Scan plugin directory and create manifest
./scripts/create_distribution_manifest.nu /path/to/plugins --output DISTRIBUTION_MANIFEST.json
```

**Output:** `DISTRIBUTION_MANIFEST.json` containing:
- All available plugins
- Plugin descriptions
- Plugin paths
- File sizes
- Metadata (version, creation date)

**Example manifest structure:**
```json
{
  "version": "1.0.0",
  "created": "2025-10-22T10:52:08Z",
  "source_directory": "/path/to/plugins",
  "total_plugins": 13,
  "plugins": [
    {
      "name": "nu_plugin_auth",
      "purpose": "Authentication (JWT, MFA)",
      "path": "/path/to/plugins/nu_plugin_auth",
      "size_bytes": 11846592
    },
    ... more plugins
  ]
}
```

### Step 2: Package Distribution

Include in your distribution:
```
distribution/
├── bin/
│   ├── nu_plugin_auth
│   ├── nu_plugin_kms
│   ├── ...
├── install_from_manifest.nu    (or ./install.nu - symlink)
└── DISTRIBUTION_MANIFEST.json   (manifest file)
```

### Step 3: User Installation

End users run the installer:

```bash
# List available plugins
./install_from_manifest.nu --list

# Install essential preset
./install_from_manifest.nu --preset essential

# Install all plugins
./install_from_manifest.nu --all

# Install specific plugins
./install_from_manifest.nu --select auth kms orchestrator

# Dry-run (preview)
./install_from_manifest.nu --preset development --check
```

## Manifest Generator

**Script:** `./scripts/create_distribution_manifest.nu`

### Usage

```bash
# Scan current directory
./scripts/create_distribution_manifest.nu

# Scan specific directory
./scripts/create_distribution_manifest.nu /path/to/plugins

# Custom output file
./scripts/create_distribution_manifest.nu /path/to/plugins --output my_manifest.json
```

### What It Does

1. Scans for plugin binaries (files matching `nu_plugin_*`)
2. Extracts plugin information (name, purpose, path, size)
3. Creates JSON manifest file
4. Ready to be included in distribution

## Distribution Installer

**Script:** `./install_from_manifest.nu`

### Usage Options

```bash
# Interactive menu
./install_from_manifest.nu

# List available plugins
./install_from_manifest.nu --list

# Use preset
./install_from_manifest.nu --preset essential   # 5 core plugins
./install_from_manifest.nu --preset development # 8 plugins
./install_from_manifest.nu --preset full        # All plugins

# Select specific plugins
./install_from_manifest.nu --select auth kms orchestrator

# Install all
./install_from_manifest.nu --all

# Dry-run (preview)
./install_from_manifest.nu --check

# Install only (skip registration)
./install_from_manifest.nu --all --install-only

# Register only (skip install)
./install_from_manifest.nu --all --register-only
```

### What It Does

1. **Loads manifest** - Reads DISTRIBUTION_MANIFEST.json
2. **Displays options** - Shows available plugins or presets
3. **User selects** - Interactive menu or command-line options
4. **Installs** - Copies selected plugins to ~/.local/bin/
5. **Registers** - Updates Nushell config (~/.config/nushell/env.nu)
6. **Confirms** - Asks user before making changes

## Available Presets

### Essential (5 plugins)
```
• nu_plugin_auth         - Authentication
• nu_plugin_kms          - Encryption
• nu_plugin_orchestrator - Orchestration
• nu_plugin_kcl          - KCL config
• nu_plugin_tera         - Templates
```

### Development (8 plugins)
```
All essential +
• nu_plugin_highlight    - Syntax highlighting
• nu_plugin_image        - Image processing
• nu_plugin_clipboard    - Clipboard
```

### Full (All custom plugins)
```
All 13 custom plugins included in distribution
```

## Example Distribution Package

```
nushell-plugins-3.5.0-darwin-arm64/
├── README.md
├── LICENSE
├── bin/
│   ├── nu_plugin_auth
│   ├── nu_plugin_clipboard
│   ├── nu_plugin_desktop_notifications
│   ├── nu_plugin_fluent
│   ├── nu_plugin_hashes
│   ├── nu_plugin_highlight
│   ├── nu_plugin_image
│   ├── nu_plugin_kcl
│   ├── nu_plugin_kms
│   ├── nu_plugin_orchestrator
│   ├── nu_plugin_port_extension
│   ├── nu_plugin_qr_maker
│   └── nu_plugin_tera
├── DISTRIBUTION_MANIFEST.json
├── install_from_manifest.nu
└── install.nu -> install_from_manifest.nu (symlink for convenience)
```

## User Quick Start

```bash
# Extract distribution
tar -xzf nushell-plugins-3.5.0-darwin-arm64.tar.gz
cd nushell-plugins-3.5.0-darwin-arm64

# See what's available
./install.nu --list

# Install essential plugins
./install.nu --preset essential

# Restart Nushell
exit && nu

# Verify
nu -c "plugin list"
```

## Build & Package Workflow

### For Distribution Maintainers

```bash
# 1. Build all plugins (custom & core)
cd nushell && cargo build --release --workspace && cd ..
cargo build --release (for each custom plugin)

# 2. Create distribution directory
mkdir -p dist/bin
cp ~/.local/bin/nu_plugin_* dist/bin/
cp nushell/target/release/nu_plugin_* dist/bin/ 2>/dev/null

# 3. Generate manifest
./scripts/create_distribution_manifest.nu dist/bin --output dist/DISTRIBUTION_MANIFEST.json

# 4. Copy installer script
cp scripts/install_from_manifest.nu dist/install_from_manifest.nu
ln -s install_from_manifest.nu dist/install.nu

# 5. Add documentation
cp README.md dist/
cp LICENSE dist/

# 6. Package for distribution
tar -czf nushell-plugins-3.5.0-darwin-arm64.tar.gz dist/
```

## File Reference

| File | Purpose |
|------|---------|
| `scripts/create_distribution_manifest.nu` | Generate manifest from plugins |
| `scripts/install_from_manifest.nu` | Install & register from manifest |
| `DISTRIBUTION_MANIFEST.json` | JSON list of available plugins |
| `~/.local/bin/nu_plugin_*` | Installed plugin binaries |
| `~/.config/nushell/env.nu` | Nushell config (plugin registrations added) |

## Features

✅ **Automatic Detection** - Scans for all available plugins
✅ **Flexible Selection** - Presets or individual plugin selection
✅ **User Choice** - No forced installations
✅ **Dry-Run** - Preview before installing
✅ **Install & Register** - Handles both steps
✅ **Clean Separation** - Install-only and register-only modes
✅ **Safe** - Confirms before making changes
✅ **Easy Distribution** - Single JSON manifest file

## FAQ

**Q: How do I update the manifest after adding new plugins?**
A: Run `create_distribution_manifest.nu` again to regenerate the manifest.

**Q: Can users install plugins after distribution is created?**
A: Only if the plugins are included in the distribution. Core Nushell plugins require a rebuild.

**Q: What if manifest is missing?**
A: Installer will fail with clear error message. User needs to generate manifest first.

**Q: Can I customize plugin purposes/descriptions?**
A: Edit the manifest JSON file manually or modify `get_plugin_purpose()` function before generating.

**Q: Do plugins need to be pre-built?**
A: Yes, distribution contains only binaries. No build tools needed by end users.

---

**Version:** 3.5.0
**Manifest Version:** 1.0.0
**Created:** 2025-10-22
**Nushell:** 0.108.0+