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\nbash\n# Scan plugin directory and create manifest\n./scripts/create_distribution_manifest.nu /path/to/plugins --output DISTRIBUTION_MANIFEST.json\n\n\nOutput: DISTRIBUTION_MANIFEST.json containing:\n\n- All available plugins\n- Plugin descriptions\n- Plugin paths\n- File sizes\n- Metadata (version, creation date)\n\nExample manifest structure:\n\njson\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\nplaintext\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\nbash\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\nScript: ./scripts/create_distribution_manifest.nu\n\n### Usage\n\nbash\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\nScript: ./install_from_manifest.nu\n\n### Usage Options\n\nbash\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\nplaintext\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\nplaintext\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\nplaintext\nAll 13 custom plugins included in distribution\n\n\n## Example Distribution Package\n\nplaintext\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\nbash\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\nbash\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\nQ: How do I update the manifest after adding new plugins?\nA: Run create_distribution_manifest.nu again to regenerate the manifest.\n\nQ: 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\nQ: What if manifest is missing?\nA: Installer will fail with clear error message. User needs to generate manifest first.\n\nQ: Can I customize plugin purposes/descriptions?\nA: Edit the manifest JSON file manually or modify get_plugin_purpose() function before generating.\n\nQ: Do plugins need to be pre-built?\nA: Yes, distribution contains only binaries. No build tools needed by end users.\n\n---\n\nVersion: 3.5.0\nManifest Version: 1.0.0\nCreated: 2025-10-22\nNushell: 0.108.0+