nushell-plugins/docs/plugin-exclusion-guide.md

# Plugin Exclusion Guide\n\n## Quick Reference\n\n**What is plugin exclusion?**: A mechanism to prevent certain plugins (like `nu_plugin_example`) from being included in distributions and installations, while keeping them available for development and testing.\n\n**Who should read this?**:\n\n- 📦 Release managers\n- 👨‍💻 Plugin developers\n- 🔧 Maintainers\n- 📚 Users who want to understand the distribution process\n\n---\n\n## Quick Start\n\n### For Users\n\n**Question**: I found `nu_plugin_example` but it's not in my installation. Why?\n\n**Answer**: The example plugin is intentionally excluded from distributions. It's a reference implementation for plugin developers, not a user-facing tool.\n\n**If you want to use it**:\n\n1. Clone the repository\n2. Build it: `just build`\n3. Use the binary directly: `./nushell/target/release/nu_plugin_example`\n\n---\n\n### For Developers\n\n**Question**: I want to exclude my plugin from distributions. How?\n\n**Answer**: Add it to the exclusion list in `etc/plugin_registry.toml`:\n\n```toml\n[distribution]\nexcluded_plugins = [\n    "nu_plugin_example",\n    "nu_plugin_my_new_plugin"  # ← Add your plugin here\n]\n```\n\nThat's it! The collection and packaging systems will automatically skip it.\n\n---\n\n### For Release Managers\n\n**Checklist before release**:\n\n1. **Verify exclusion list is correct**:\n\n   ```bash\n   nu -c "open ./etc/plugin_registry.toml | get distribution.excluded_plugins"\n   ```\n\n2. **Verify collection respects it**:\n\n   ```bash\n   just collect\n   find distribution -name "*example*"  # Should find nothing\n   ```\n\n3. **Verify packaging respects it**:\n\n   ```bash\n   just pack-full\n   tar -tzf bin_archives/*.tar.gz | grep example  # Should find nothing\n   ```\n\n4. **Verify builds still include everything** (for testing):\n\n   ```bash\n   just build\n   ls nushell/target/release/ | grep example  # Should find the binary\n   ```\n\n---\n\n## Common Tasks\n\n### Task 1: Add a Plugin to Exclusion List\n\n**Scenario**: You have a new reference plugin that shouldn't be shipped to users.\n\n**Steps**:\n\n1. Create your plugin in `nushell/crates/nu_plugin_myref/`\n2. Update `etc/plugin_registry.toml`:\n\n   ```toml\n   [distribution]\n   excluded_plugins = [\n       "nu_plugin_example",\n       "nu_plugin_myref"  # ← Add here\n   ]\n   ```\n\n3. Update `scripts/templates/default_config.nu` - remove it from the `plugin_binaries` list if it was there\n4. Test:\n\n   ```bash\n   just collect && find distribution -name "*myref*"  # Should be empty\n   ```\n\n---\n\n### Task 2: Remove a Plugin from Exclusion List\n\n**Scenario**: Your reference plugin is now stable and ready for distribution.\n\n**Steps**:\n\n1. Update `etc/plugin_registry.toml`:\n\n   ```toml\n   [distribution]\n   excluded_plugins = [\n       "nu_plugin_example"  # ← Removed your plugin\n   ]\n   ```\n\n2. Update `scripts/templates/default_config.nu` - add it to the `plugin_binaries` list if you want auto-loading\n3. Test:\n\n   ```bash\n   just collect && find distribution -name "*myref*"  # Should exist now\n   ```\n\n---\n\n### Task 3: Check Current Build Includes Excluded Plugin\n\n**Scenario**: You want to verify that excluded plugins are still being built.\n\n**Steps**:\n\n```bash\n# Build everything including excluded plugins\njust build\n\n# Verify excluded plugin was built\nls nushell/target/release/nu_plugin_example\n# Output: nushell/target/release/nu_plugin_example\n```\n\n**Why?** Excluded plugins are still useful for:\n\n- Testing and validation\n- Reference implementations\n- Developer documentation\n- Internal reference\n\n---\n\n### Task 4: Understand Distribution Workflow\n\n**Scenario**: You want to understand how plugins flow through the build/collect/package process.\n\n**Diagram**:\n\n```plaintext\nSOURCE (all plugins built)\n├── nu_plugin_example (excluded)\n├── nu_plugin_auth\n├── nu_plugin_kms\n└── ... others\n\n  ↓ (just build - NO filtering)\n\nBUILD OUTPUT (target/release)\n├── nu_plugin_example ✅ (built)\n├── nu_plugin_auth ✅ (built)\n├── nu_plugin_kms ✅ (built)\n└── ... others ✅ (built)\n\n  ↓ (just collect - WITH filtering)\n\nCOLLECTION (distribution/)\n├── nu_plugin_example ❌ (excluded)\n├── nu_plugin_auth ✅ (collected)\n├── nu_plugin_kms ✅ (collected)\n└── ... others ✅ (collected)\n\n  ↓ (just pack - WITH filtering)\n\nPACKAGING (bin_archives/)\n├── nushell-0.109.0-linux-x64.tar.gz\n│   ├── nu\n│   ├── nu_plugin_auth ✅\n│   ├── nu_plugin_kms ✅\n│   └── ... (no example plugin)\n└── nushell-0.109.0-darwin-arm64.tar.gz\n    ├── nu\n    ├── nu_plugin_auth ✅\n    ├── nu_plugin_kms ✅\n    └── ... (no example plugin)\n\n  ↓ (installation)\n\nUSER SYSTEM\n├── ~/.local/bin/nu ✅\n├── ~/.local/bin/nu_plugin_auth ✅\n├── ~/.local/bin/nu_plugin_kms ✅\n├── ~/.config/nushell/env.nu\n└── ~/.config/nushell/config.nu (auto-loads auth, kms; example not in list)\n```\n\n---\n\n## Technical Details\n\n### How Exclusion Works\n\n**Mechanism**: The system reads `etc/plugin_registry.toml` and filters at two points:\n\n1. **Collection** (`just collect` / `just collect-full`):\n   - Reads exclusion list from registry\n   - Skips excluded plugins during binary collection\n   - Result: `distribution/` dir doesn't have excluded plugins\n\n2. **Packaging** (`just pack` / `just pack-full`):\n   - Reads exclusion list from registry\n   - Skips excluded plugins during package creation\n   - Result: `bin_archives/*.tar.gz` don't have excluded plugins\n\n3. **Installation** (auto-load configuration):\n   - `scripts/templates/default_config.nu` manually removes excluded plugins from the auto-load list\n   - Result: User installations don't auto-load excluded plugins\n\n### Files Involved\n\n| File | Role |\n|------|------|\n| `etc/plugin_registry.toml` | Source of truth for exclusion list |\n| `scripts/collect_full_binaries.nu` | Implements collection-time filtering |\n| `scripts/create_distribution_packages.nu` | Implements packaging-time filtering |\n| `scripts/templates/default_config.nu` | Defines auto-load list (manually edited) |\n| `justfile` + `justfiles/*.just` | Provides build/collect/pack commands |\n\n### Registry Format\n\n```toml\n[distribution]\nexcluded_plugins = [\n    "nu_plugin_example"        # Plugin directory name\n]\nreason = "Reference plugin"    # Documentation (optional)\n```\n\n**Key Points**:\n\n- `excluded_plugins` is a list of plugin directory names (not binary names)\n- Must match the `nu_plugin_*` directory in the repo\n- Case-sensitive\n- Empty list `[]` means no exclusions\n\n---\n\n## Troubleshooting\n\n### Problem: Excluded Plugin Still Appears in Distribution\n\n**Possible Causes**:\n\n1. Registry file not saved properly\n2. Collection script using cached data\n3. Plugin name mismatch\n\n**Solution**:\n\n```bash\n# Verify registry is correct\nnu -c "open ./etc/plugin_registry.toml | get distribution.excluded_plugins"\n\n# Clean and rebuild\nrm -rf distribution bin_archives\njust collect\nfind distribution -name "*example*"  # Should be empty\n```\n\n---\n\n### Problem: Can't Find Excluded Plugin After Build\n\n**Expected Behavior**: Excluded plugins ARE still built (just not distributed)\n\n**Verification**:\n\n```bash\njust build\nls nushell/target/release/nu_plugin_example  # Should exist\n\n# If it doesn't, the plugin may not be in the build system\njust build-nushell --verbose\n```\n\n---\n\n### Problem: Manual Plugin Registration Failing\n\n**Issue**: User manually adds excluded plugin but it doesn't work\n\n**Cause**: Plugin binary not in PATH\n\n**Solution**:\n\n```bash\n# Build the plugin\njust build\n\n# Use full path\n./nushell/target/release/nu_plugin_example --version\n\n# Or install it manually\ncp ./nushell/target/release/nu_plugin_example ~/.local/bin/\nnu -c "plugin add ~/.local/bin/nu_plugin_example"\n```\n\n---\n\n## FAQs\n\n**Q: Will my excluded plugin still be tested?**\nA: Yes. Excluded plugins are still built and tested. They're only excluded from user-facing distributions.\n\n**Q: Can I exclude a plugin from builds but not distributions?**\nA: No, the current system doesn't support this. The exclusion system only affects distribution. To exclude from builds, use Cargo features.\n\n**Q: Can different distributions have different exclusion lists?**\nA: Not currently, but this is planned as a future enhancement (profile-based exclusions).\n\n**Q: What happens if I exclude a plugin that doesn't exist?**\nA: It's ignored. The filtering works by checking if a plugin name is in the exclusion list, so non-existent plugins are silently skipped.\n\n**Q: Can I exclude plugins selectively (e.g., exclude from macOS but not Linux)?**\nA: Not currently. This would require platform-based exclusion profiles (future enhancement).\n\n---\n\n## Best Practices\n\n### ✅ DO\n\n- **Update the comment** in config when excluding/including plugins\n- **Test after changes**: `just collect && just pack-full && just build`\n- **Document the reason** in `plugin_registry.toml` (optional but recommended)\n- **Run verification** before releases (see Release Manager checklist)\n- **Keep registry clean** - don't exclude plugins you won't maintain\n\n### ❌ DON'T\n\n- **Edit multiple files** - only touch `etc/plugin_registry.toml` for the core change\n- **Assume exclusion happens at build time** - it only happens during collect/pack\n- **Forget to test** - exclusion changes should be verified before release\n- **Add plugins to exclusion list without documenting why** in the code\n- **Exclude plugins that users depend on** - use this only for reference/experimental plugins\n\n---\n\n## Integration with CI/CD\n\n### GitHub Actions Example\n\n```yaml\nname: Distribution Release\n\non:\n  push:\n    tags:\n      - 'v*'\n\njobs:\n  release:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n\n      # Verify exclusion list\n      - name: Verify Exclusion List\n        run: |\n          nu -c "open ./etc/plugin_registry.toml | get distribution.excluded_plugins"\n\n      # Build (includes all plugins)\n      - name: Build\n        run: just build-full-release\n\n      # Collect (excludes specified plugins)\n      - name: Collect\n        run: just collect-full\n\n      # Verify excluded plugins not in distribution\n      - name: Verify Exclusions\n        run: |\n          ! find distribution -name "*example*"\n\n      # Package\n      - name: Package\n        run: just pack-full-checksums\n\n      # Release\n      - name: Create Release\n        uses: softprops/action-gh-release@v1\n        with:\n          files: bin_archives/*\n```\n\n---\n\n## See Also\n\n- **Architecture Details**: [`docs/architecture/plugin-exclusion-system.md`](./architecture/plugin-exclusion-system.md)\n- **Build System**: [`docs/building.md`](./building.md)\n- **Plugin Development**: `nushell/crates/nu_plugin_example/` (reference implementation)\n- **Registry Configuration**: `etc/plugin_registry.toml`\n\n---\n\n**Version**: 1.0.0\n**Last Updated**: 2025-12-03\n**Status**: Stable