nushell-plugins/docs/architecture/README.md

# 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](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md)\n\n**Status**: ✅ Accepted & Implemented\n**Date**: 2025-12-03\n\nA configuration-driven system for excluding reference/documentation plugins from distributions while keeping them available for development and testing.\n\n**Key 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\n**When 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](./PLUGIN_EXCLUSION_SYSTEM.md)\n\n**Status**: ✅ Complete\n**Version**: 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\n**Sections**:\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\n**When 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](../PLUGIN_EXCLUSION_GUIDE.md)\n\n**Status**: ✅ Complete\n**Version**: 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\n**Sections**:\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\n**When 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)](../PLUGIN_EXCLUSION_GUIDE.md#for-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)](../PLUGIN_EXCLUSION_GUIDE.md#for-developers)\nThen read: [Technical Architecture](./PLUGIN_EXCLUSION_SYSTEM.md)\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](../PLUGIN_EXCLUSION_GUIDE.md#for-release-managers)\nThen read: [ADR-001](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md)\n\n- Pre-release verification steps\n- How to test exclusions\n- Decision rationale for documentation\n\n**🔧 Maintainers/Architects**:\nStart with: [ADR-001](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md)\nThen read: [Technical Architecture](./PLUGIN_EXCLUSION_SYSTEM.md)\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](../PLUGIN_EXCLUSION_GUIDE.md#task-1-add-a-plugin-to-exclusion-list)\n\n**"I want to remove a plugin from exclusion"**:\n→ [Plugin Exclusion Guide - Task 2](../PLUGIN_EXCLUSION_GUIDE.md#task-2-remove-a-plugin-from-exclusion-list)\n\n**"I need to understand the workflow"**:\n→ [Plugin Exclusion Guide - Task 4](../PLUGIN_EXCLUSION_GUIDE.md#task-4-understand-distribution-workflow)\n\n**"Something isn't working"**:\n→ [Plugin Exclusion Guide - Troubleshooting](../PLUGIN_EXCLUSION_GUIDE.md#troubleshooting)\n\n**"I need to extend the system"**:\n→ [Technical Architecture - Future Enhancements](./PLUGIN_EXCLUSION_SYSTEM.md#future-enhancements)\n\n**"I need to integrate with CI/CD"**:\n→ [Plugin Exclusion Guide - CI/CD Integration](../PLUGIN_EXCLUSION_GUIDE.md#integration-with-cicd)\n\n---\n\n## File Organization\n\n```plaintext\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](../PLUGIN_EXCLUSION_GUIDE.md) | Practical how-to's | 15 min |\n| [Technical Architecture](./PLUGIN_EXCLUSION_SYSTEM.md) | Deep technical details | 30 min |\n| [ADR-001](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md) | 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\n**Key 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\n```plaintext\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\n**Example**:\n\n```toml\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\n**Functions**:\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\n**Functions**:\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\n```bash\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](../PLUGIN_EXCLUSION_GUIDE.md#for-release-managers) for complete pre-release checklist.\n\n---\n\n## Contact & Questions\n\nFor questions about:\n\n- **Usage**: See [Plugin Exclusion Guide](../PLUGIN_EXCLUSION_GUIDE.md)\n- **Design**: See [ADR-001](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md)\n- **Implementation**: See [Technical Architecture](./PLUGIN_EXCLUSION_SYSTEM.md)\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\n**Last Updated**: 2025-12-03\n**Status**: Complete & Stable\n**Maintainer**: Project Team