nushell-plugins/guides/distribution-installer-workflow.md

# Nushell Plugin Distribution Installer Workflow\n\nComplete workflow for creating and distributing Nushell plugins with manifest-based installation.\n\n## Overview\n\nThe distribution installer system has three main components:\n\n1. **Manifest Generator** - Scans plugins and creates a manifest\n2. **Manifest File** - JSON file listing all available plugins\n3. **Distribution Installer** - Lets users choose which plugins to install/register\n\n## Workflow\n\n### Step 1: Create Distribution Manifest\n\nWhen you're packaging the distribution:\n\n```bash\n# Scan plugin directory and create manifest\n./scripts/create_distribution_manifest.nu /path/to/plugins --output DISTRIBUTION_MANIFEST.json\n```\n\n**Output:** `DISTRIBUTION_MANIFEST.json` containing:\n\n- All available plugins\n- Plugin descriptions\n- Plugin paths\n- File sizes\n- Metadata (version, creation date)\n\n**Example manifest structure:**\n\n```json\n{\n  "version": "1.0.0",\n  "created": "2025-10-22T10:52:08Z",\n  "source_directory": "/path/to/plugins",\n  "total_plugins": 13,\n  "plugins": [\n    {\n      "name": "nu_plugin_auth",\n      "purpose": "Authentication (JWT, MFA)",\n      "path": "/path/to/plugins/nu_plugin_auth",\n      "size_bytes": 11846592\n    },\n    ... more plugins\n  ]\n}\n```\n\n### Step 2: Package Distribution\n\nInclude in your distribution:\n\n```plaintext\ndistribution/\n├── bin/\n│   ├── nu_plugin_auth\n│   ├── nu_plugin_kms\n│   ├── ...\n├── install_from_manifest.nu    (or ./install.nu - symlink)\n└── DISTRIBUTION_MANIFEST.json   (manifest file)\n```\n\n### Step 3: User Installation\n\nEnd users run the installer:\n\n```bash\n# List available plugins\n./install_from_manifest.nu --list\n\n# Install essential preset\n./install_from_manifest.nu --preset essential\n\n# Install all plugins\n./install_from_manifest.nu --all\n\n# Install specific plugins\n./install_from_manifest.nu --select auth kms orchestrator\n\n# Dry-run (preview)\n./install_from_manifest.nu --preset development --check\n```\n\n## Manifest Generator\n\n**Script:** `./scripts/create_distribution_manifest.nu`\n\n### Usage\n\n```bash\n# Scan current directory\n./scripts/create_distribution_manifest.nu\n\n# Scan specific directory\n./scripts/create_distribution_manifest.nu /path/to/plugins\n\n# Custom output file\n./scripts/create_distribution_manifest.nu /path/to/plugins --output my_manifest.json\n```\n\n### What It Does\n\n1. Scans for plugin binaries (files matching `nu_plugin_*`)\n2. Extracts plugin information (name, purpose, path, size)\n3. Creates JSON manifest file\n4. Ready to be included in distribution\n\n## Distribution Installer\n\n**Script:** `./install_from_manifest.nu`\n\n### Usage Options\n\n```bash\n# Interactive menu\n./install_from_manifest.nu\n\n# List available plugins\n./install_from_manifest.nu --list\n\n# Use preset\n./install_from_manifest.nu --preset essential   # 5 core plugins\n./install_from_manifest.nu --preset development # 8 plugins\n./install_from_manifest.nu --preset full        # All plugins\n\n# Select specific plugins\n./install_from_manifest.nu --select auth kms orchestrator\n\n# Install all\n./install_from_manifest.nu --all\n\n# Dry-run (preview)\n./install_from_manifest.nu --check\n\n# Install only (skip registration)\n./install_from_manifest.nu --all --install-only\n\n# Register only (skip install)\n./install_from_manifest.nu --all --register-only\n```\n\n### What It Does\n\n1. **Loads manifest** - Reads DISTRIBUTION_MANIFEST.json\n2. **Displays options** - Shows available plugins or presets\n3. **User selects** - Interactive menu or command-line options\n4. **Installs** - Copies selected plugins to ~/.local/bin/\n5. **Registers** - Updates Nushell config (~/.config/nushell/env.nu)\n6. **Confirms** - Asks user before making changes\n\n## Available Presets\n\n### Essential (5 plugins)\n\n```plaintext\n• nu_plugin_auth         - Authentication\n• nu_plugin_kms          - Encryption\n• nu_plugin_orchestrator - Orchestration\n• nu_plugin_kcl          - KCL config\n• nu_plugin_tera         - Templates\n```\n\n### Development (8 plugins)\n\n```plaintext\nAll essential +\n• nu_plugin_highlight    - Syntax highlighting\n• nu_plugin_image        - Image processing\n• nu_plugin_clipboard    - Clipboard\n```\n\n### Full (All custom plugins)\n\n```plaintext\nAll 13 custom plugins included in distribution\n```\n\n## Example Distribution Package\n\n```plaintext\nnushell-plugins-3.5.0-darwin-arm64/\n├── README.md\n├── LICENSE\n├── bin/\n│   ├── nu_plugin_auth\n│   ├── nu_plugin_clipboard\n│   ├── nu_plugin_desktop_notifications\n│   ├── nu_plugin_fluent\n│   ├── nu_plugin_hashes\n│   ├── nu_plugin_highlight\n│   ├── nu_plugin_image\n│   ├── nu_plugin_kcl\n│   ├── nu_plugin_kms\n│   ├── nu_plugin_orchestrator\n│   ├── nu_plugin_port_extension\n│   ├── nu_plugin_qr_maker\n│   └── nu_plugin_tera\n├── DISTRIBUTION_MANIFEST.json\n├── install_from_manifest.nu\n└── install.nu -> install_from_manifest.nu (symlink for convenience)\n```\n\n## User Quick Start\n\n```bash\n# Extract distribution\ntar -xzf nushell-plugins-3.5.0-darwin-arm64.tar.gz\ncd nushell-plugins-3.5.0-darwin-arm64\n\n# See what's available\n./install.nu --list\n\n# Install essential plugins\n./install.nu --preset essential\n\n# Restart Nushell\nexit && nu\n\n# Verify\nnu -c "plugin list"\n```\n\n## Build & Package Workflow\n\n### For Distribution Maintainers\n\n```bash\n# 1. Build all plugins (custom & core)\ncd nushell && cargo build --release --workspace && cd ..\ncargo build --release (for each custom plugin)\n\n# 2. Create distribution directory\nmkdir -p dist/bin\ncp ~/.local/bin/nu_plugin_* dist/bin/\ncp nushell/target/release/nu_plugin_* dist/bin/ 2>/dev/null\n\n# 3. Generate manifest\n./scripts/create_distribution_manifest.nu dist/bin --output dist/DISTRIBUTION_MANIFEST.json\n\n# 4. Copy installer script\ncp scripts/install_from_manifest.nu dist/install_from_manifest.nu\nln -s install_from_manifest.nu dist/install.nu\n\n# 5. Add documentation\ncp README.md dist/\ncp LICENSE dist/\n\n# 6. Package for distribution\ntar -czf nushell-plugins-3.5.0-darwin-arm64.tar.gz dist/\n```\n\n## File Reference\n\n| File | Purpose |\n|------|---------|\n| `scripts/create_distribution_manifest.nu` | Generate manifest from plugins |\n| `scripts/install_from_manifest.nu` | Install & register from manifest |\n| `DISTRIBUTION_MANIFEST.json` | JSON list of available plugins |\n| `~/.local/bin/nu_plugin_*` | Installed plugin binaries |\n| `~/.config/nushell/env.nu` | Nushell config (plugin registrations added) |\n\n## Features\n\n✅ **Automatic Detection** - Scans for all available plugins\n✅ **Flexible Selection** - Presets or individual plugin selection\n✅ **User Choice** - No forced installations\n✅ **Dry-Run** - Preview before installing\n✅ **Install & Register** - Handles both steps\n✅ **Clean Separation** - Install-only and register-only modes\n✅ **Safe** - Confirms before making changes\n✅ **Easy Distribution** - Single JSON manifest file\n\n## FAQ\n\n**Q: How do I update the manifest after adding new plugins?**\nA: Run `create_distribution_manifest.nu` again to regenerate the manifest.\n\n**Q: Can users install plugins after distribution is created?**\nA: Only if the plugins are included in the distribution. Core Nushell plugins require a rebuild.\n\n**Q: What if manifest is missing?**\nA: Installer will fail with clear error message. User needs to generate manifest first.\n\n**Q: Can I customize plugin purposes/descriptions?**\nA: Edit the manifest JSON file manually or modify `get_plugin_purpose()` function before generating.\n\n**Q: Do plugins need to be pre-built?**\nA: Yes, distribution contains only binaries. No build tools needed by end users.\n\n---\n\n**Version:** 3.5.0\n**Manifest Version:** 1.0.0\n**Created:** 2025-10-22\n**Nushell:** 0.108.0+