4b92aa764a
Some checks failed
Build and Test / Validate Setup (push) Has been cancelled
Build and Test / Build (darwin-amd64) (push) Has been cancelled
Build and Test / Build (darwin-arm64) (push) Has been cancelled
Build and Test / Build (linux-amd64) (push) Has been cancelled
Build and Test / Build (windows-amd64) (push) Has been cancelled
Build and Test / Build (linux-arm64) (push) Has been cancelled
Build and Test / Security Audit (push) Has been cancelled
Build and Test / Package Results (push) Has been cancelled
Build and Test / Quality Gate (push) Has been cancelled
293 lines
7.5 KiB
Markdown
293 lines
7.5 KiB
Markdown
# 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+
|