2026-03-11 03:22:42 +00:00
|
|
|
# Plugin Exclusion System (v1.0.0)\n\n## Overview\n\nThe Plugin Exclusion System is a configuration-driven mechanism that allows selective exclusion of plugins from distributions, collections, and installations while maintaining full availability for development, testing, and reference purposes.\n\n**Status**: Implemented (2025-12-03)\n**Purpose**: Exclude reference/documentation plugins (like `nu_plugin_example`) from end-user distributions\n\n---\n\n## Architecture\n\n### Design Principle\n\n**Single Source of Truth**: All plugin exclusions are centrally defined in `etc/plugin_registry.toml`, ensuring consistency across all distribution-related operations.\n\n```plaintext\nplugin_registry.toml (source of truth)\n ↓\n ┌───┴────────────────────────────────────┐\n ↓ ↓\ncollect_full_binaries.nu create_distribution_packages.nu\n(collection operations) (packaging operations)\n ↓ ↓\ndistribution/ directories bin_archives/ packages\n```\n\n### Configuration\n\n#### Plugin Registry Entry\n\n**File**: `etc/plugin_registry.toml`\n\n```toml\n[distribution]\nexcluded_plugins = [\n "nu_plugin_example"\n]\nreason = "Reference/documentation plugin - excluded from distributions, installations, and collections. Still included in build and test for validation."\n```\n\n**Structure**:\n\n- `excluded_plugins` (required): List of plugin names to exclude from distributions\n- `reason` (optional): Documentation of why plugins are excluded\n\n**Adding New Exclusions**:\n\n```toml\n[distribution]\nexcluded_plugins = [\n "nu_plugin_example",\n "nu_plugin_new_reference" # Add here\n]\n```\n\n---\n\n## Implementation\n\n### 1. Collection System (`scripts/collect_full_binaries.nu`)\n\n#### Helper Function\n\n```nu\ndef get_excluded_plugins []: nothing -> list<string> {\n try {\n let registry_path = "./etc/plugin_registry.toml"\n if not ($registry_path | path exists) {\n return []\n }\n\n let registry_content = open $registry_path\n let excluded = try {\n $registry_content.distribution.excluded_plugins\n } catch {\n []\n }\n\n return $excluded\n } catch {\n return []\n }\n}\n```\n\n**Key Features**:\n\n- Reads exclusion list from registry\n- Graceful error handling (returns empty list if registry missing/malformed)\n- Non-blocking (collection continues even if registry unavailable)\n\n#### Workspace Plugins Filtering\n\n```nu\ndef get_workspace_plugins_info [platform: string, use_release: bool, profile: string]: nothing -> list<record> {\n let excluded_plugins = (get_excluded_plugins)\n\n let workspace_plugins = [\n "nu_plugin_custom_values"\n "nu_plugin_example"\n "nu_plugin_formats"\n # ... other plugins\n ]\n\n # Filter out excluded plugins\n let available_plugins = $workspace_plugins | where { |p| $p not-in $excluded_plugins }\n\n # Process only available plugins\n for plugin in $available_plugins {\n # ... collection logic\n }\n}\n```\n\n#### Custom Plugins Filtering\n\n```nu\ndef get_custom_plugins_info [platform: string, use_release: bool, profile: string]: nothing -> list<record> {\n let excluded_plugins = (get_excluded_plugins)\n\n let plugin_dirs = (glob $"nu_plugin_*")\n | where ($it | path type) == "dir"\n | where ($it | path basename) != "nushell"\n | where { |p| ($p | path basename) not-in $excluded_plugins } # Filter excluded\n | each { |p| $p | path basename }\n\n # Process remaining plugins\n}\n```\n\n### 2. Packaging System (`scripts/create_distribution_packages.nu`)\n\n#### Helper Function\n\n```nu\ndef get_excluded_plugins_dist []: nothing -> list<string> {\n try {\n let registry_path = "./etc/plugin_registry.toml"\n if not ($registry_path | path exists) {\n return []\n }\n\n
|
