nushell-plugins/docs/architecture

Architecture Documentation\n\nWelcome to the architecture documentation for the nushell-plugins project. This directory contains Architecture Decision Records (ADRs), design documents, and technical guides.\n\n---\n\n## Architecture Decision Records (ADRs)\n\n### ADR-001: Plugin Exclusion System\n\nStatus: ✅ Accepted & Implemented\nDate: 2025-12-03\n\nA configuration-driven system for excluding reference/documentation plugins from distributions while keeping them available for development and testing.\n\nKey Points:\n\n- Single source of truth in etc/plugin_registry.toml\n- Non-breaking - doesn't affect builds, tests, or development\n- Centralized filtering at collection and packaging stages\n- Foundation for future profile-based and conditional exclusions\n\nWhen to Read: If you want to understand WHY the exclusion system was implemented and how design decisions were made.\n\n---\n\n## Technical Specifications\n\n### Plugin Exclusion System - Technical Architecture\n\nStatus: ✅ Complete\nVersion: 1.0.0\n\nDeep-dive into the technical implementation of plugin exclusions, including:\n\n- How the system works under the hood\n- Code implementation details\n- Error handling and resilience\n- Integration points with build/collect/package workflows\n- Performance impact analysis\n- Future enhancement possibilities\n\nSections:\n\n- Overview and design principles\n- Configuration details\n- Implementation in collection system\n- Implementation in packaging system\n- Implementation in installation configuration\n- Behavior matrix (what happens in each scenario)\n- Use cases and examples\n- Error handling strategies\n- Maintenance procedures\n- Testing and verification\n\nWhen to Read: If you need to understand HOW the system works, maintain it, or extend it.\n\n---\n\n## Guides & Documentation\n\n### Plugin Exclusion Guide - Quick Reference & Troubleshooting\n\nStatus: ✅ Complete\nVersion: 1.0.0\n\nUser-friendly guide covering:\n\n- Quick reference for different user types\n- Common tasks (add/remove exclusions, verify builds, etc.)\n- Technical details for developers\n- Troubleshooting section\n- FAQs\n- Best practices\n- CI/CD integration examples\n\nSections:\n\n- Quick start for users, developers, and release managers\n- Common tasks with step-by-step instructions\n- Technical workflow diagrams\n- Troubleshooting guide\n- FAQs\n- Best practices (DO/DON'T)\n- CI/CD integration examples\n\nWhen to Read: If you're learning the system, performing a task related to exclusions, or troubleshooting issues.\n\n---\n\n## Navigation Guide\n\n### By User Role\n\n**👤 End Users**:\nStart with: Plugin Exclusion Guide - Quick Start (Users)\n\n- Explains why some plugins aren't in distributions\n- Shows how to access excluded plugins if needed\n\n**👨‍💻 Plugin Developers**:\nStart with: Plugin Exclusion Guide - Quick Start (Developers)\nThen read: Technical Architecture\n\n- How to exclude your plugin during development\n- How the filtering system works\n- Implementation details\n\n**📦 Release Managers**:\nStart with: Plugin Exclusion Guide - Release Checklist\nThen read: ADR-001\n\n- Pre-release verification steps\n- How to test exclusions\n- Decision rationale for documentation\n\n**🔧 Maintainers/Architects**:\nStart with: ADR-001\nThen read: Technical Architecture\n\n- Design decisions and trade-offs\n- Implementation details\n- Extension points for future enhancements\n\n### By Task\n\n**"I want to exclude a plugin":\n→ Plugin Exclusion Guide - Task 1\n\n"I want to remove a plugin from exclusion":\n→ Plugin Exclusion Guide - Task 2\n\n"I need to understand the workflow":\n→ Plugin Exclusion Guide - Task 4\n\n"Something isn't working":\n→ Plugin Exclusion Guide - Troubleshooting\n\n"I need to extend the system":\n→ Technical Architecture - Future Enhancements\n\n"I need to integrate with CI/CD":\n→ Plugin Exclusion Guide - CI/CD Integration\n\n---\n\n## File Organization\n\nplaintext\ndocs/\n├── README.md (this file)\n├── BUILDING.md\n├── PLUGIN_EXCLUSION_GUIDE.md ← User guide & troubleshooting\n├── PROVISIONING_PLUGINS_SUMMARY.md\n└── architecture/\n ├── README.md ← You are here\n ├── ADR-001-PLUGIN_EXCLUSION_SYSTEM.md ← Decision record\n └── PLUGIN_EXCLUSION_SYSTEM.md ← Technical spec\n\n\n---\n\n## Quick Links\n\n| Document | Purpose | Read Time |\n|----------|---------|-----------|\n| Plugin Exclusion Guide | Practical how-to's | 15 min |\n| Technical Architecture | Deep technical details | 30 min |\n| ADR-001 | Decision & rationale | 20 min |\n\n---\n\n## Key Concepts\n\n### Plugin Exclusion\n\nMechanism to prevent certain plugins (typically reference implementations) from being included in distributions and installations, while keeping them available for development, testing, and reference purposes.\n\nKey Points**:\n\n- Controlled by etc/plugin_registry.toml\n- Affects ONLY collection and packaging (not build)\n- Used for reference plugins, experimental features, internal tools\n- Does NOT prevent building or testing\n\n### Distribution Pipeline\n\nplaintext\nSource Code\n ↓ (just build)\nBuild Output (all plugins)\n ↓ (just collect)\nCollection (filtered)\n ↓ (just pack)\nPackages (filtered)\n ↓ (install)\nUser Systems (filtered)\n\n\n### Filtering Points\n\n1. Collection - skips excluded when collecting binaries\n2. Packaging - skips excluded when creating archives\n3. Configuration - config template doesn't auto-load excluded\n4. NOT at Build - all plugins still built for testing\n\n---\n\n## System Components\n\n### Configuration (etc/plugin_registry.toml)\n\nSource of truth for which plugins are excluded from distributions.\n\nExample:\n\ntoml\n[distribution]\nexcluded_plugins = [\n "nu_plugin_example"\n]\nreason = "Reference implementation"\n\n\n### Collection System (scripts/collect_full_binaries.nu)\n\nGathers built binaries for distribution, excluding specified plugins.\n\nFunctions:\n\n- get_excluded_plugins() - loads exclusion list\n- get_workspace_plugins_info() - filters workspace plugins\n- get_custom_plugins_info() - filters custom plugins\n\n### Packaging System (scripts/create_distribution_packages.nu)\n\nCreates distribution archives, excluding specified plugins.\n\nFunctions:\n\n- get_excluded_plugins_dist() - loads exclusion list\n- get_plugin_components() - filters plugin components\n\n### Installation Configuration (scripts/templates/default_config.nu)\n\nDefault Nushell configuration that doesn't auto-load excluded plugins.\n\n---\n\n## Testing & Verification\n\n### Basic Verification\n\nbash\n# Check exclusion list is readable\nnu -c "open ./etc/plugin_registry.toml | get distribution.excluded_plugins"\n\n# Verify collection excludes properly\njust collect\nfind distribution -name "*example*" # Should be empty\n\n# Verify packaging excludes properly\njust pack-full\ntar -tzf bin_archives/*.tar.gz | grep example # Should be empty\n\n# Verify builds still include everything\njust build\nls nushell/target/release/nu_plugin_example # Should exist\n\n\n### Release Verification\n\nSee Plugin Exclusion Guide - Release Checklist for complete pre-release checklist.\n\n---\n\n## Contact & Questions\n\nFor questions about:\n\n- Usage: See Plugin Exclusion Guide\n- Design: See ADR-001\n- Implementation: See Technical Architecture\n- Issues: Check the project issue tracker\n\n---\n\n## Version Information\n\n| Component | Version | Updated |\n|-----------|---------|---------|\n| ADR-001 | 1.0 | 2025-12-03 |\n| Technical Spec | 1.0 | 2025-12-03 |\n| User Guide | 1.0 | 2025-12-03 |\n| System | v1.0.0 | 2025-12-03 |\n\n---\n\nLast Updated: 2025-12-03\nStatus: Complete & Stable\nMaintainer: Project Team