nushell-plugins/docs/architecture/README.md

Architecture Documentation

Welcome to the architecture documentation for the nushell-plugins project. This directory contains Architecture Decision Records (ADRs), design documents, and technical guides.

---

Architecture Decision Records (ADRs)

ADR-001: Plugin Exclusion System

Status: ✅ Accepted & Implemented Date: 2025-12-03

A configuration-driven system for excluding reference/documentation plugins from distributions while keeping them available for development and testing.

Key Points:

• Single source of truth in etc/plugin_registry.toml
• Non-breaking - doesn't affect builds, tests, or development
• Centralized filtering at collection and packaging stages
• Foundation for future profile-based and conditional exclusions

When to Read: If you want to understand WHY the exclusion system was implemented and how design decisions were made.

---

Technical Specifications

Plugin Exclusion System - Technical Architecture

Status: ✅ Complete Version: 1.0.0

Deep-dive into the technical implementation of plugin exclusions, including:

• How the system works under the hood
• Code implementation details
• Error handling and resilience
• Integration points with build/collect/package workflows
• Performance impact analysis
• Future enhancement possibilities

Sections:

• Overview and design principles
• Configuration details
• Implementation in collection system
• Implementation in packaging system
• Implementation in installation configuration
• Behavior matrix (what happens in each scenario)
• Use cases and examples
• Error handling strategies
• Maintenance procedures
• Testing and verification

When to Read: If you need to understand HOW the system works, maintain it, or extend it.

---

Guides & Documentation

Plugin Exclusion Guide - Quick Reference & Troubleshooting

Status: ✅ Complete Version: 1.0.0

User-friendly guide covering:

• Quick reference for different user types
• Common tasks (add/remove exclusions, verify builds, etc.)
• Technical details for developers
• Troubleshooting section
• FAQs
• Best practices
• CI/CD integration examples

Sections:

• Quick start for users, developers, and release managers
• Common tasks with step-by-step instructions
• Technical workflow diagrams
• Troubleshooting guide
• FAQs
• Best practices (DO/DON'T)
• CI/CD integration examples

When to Read: If you're learning the system, performing a task related to exclusions, or troubleshooting issues.

---

Navigation Guide

By User Role

👤 End Users: Start with: Plugin Exclusion Guide - Quick Start (Users)

• Explains why some plugins aren't in distributions
• Shows how to access excluded plugins if needed

👨‍💻 Plugin Developers: Start with: Plugin Exclusion Guide - Quick Start (Developers) Then read: Technical Architecture

• How to exclude your plugin during development
• How the filtering system works
• Implementation details

📦 Release Managers: Start with: Plugin Exclusion Guide - Release Checklist Then read: ADR-001

• Pre-release verification steps
• How to test exclusions
• Decision rationale for documentation

🔧 Maintainers/Architects: Start with: ADR-001 Then read: Technical Architecture

• Design decisions and trade-offs
• Implementation details
• Extension points for future enhancements

By Task

"I want to exclude a plugin": → Plugin Exclusion Guide - Task 1

"I want to remove a plugin from exclusion": → Plugin Exclusion Guide - Task 2

"I need to understand the workflow": → Plugin Exclusion Guide - Task 4

"Something isn't working": → Plugin Exclusion Guide - Troubleshooting

"I need to extend the system": → Technical Architecture - Future Enhancements

"I need to integrate with CI/CD": → Plugin Exclusion Guide - CI/CD Integration

---

File Organization

docs/
├── README.md (this file)
├── BUILDING.md
├── PLUGIN_EXCLUSION_GUIDE.md     ← User guide & troubleshooting
├── PROVISIONING_PLUGINS_SUMMARY.md
└── architecture/
    ├── README.md                  ← You are here
    ├── ADR-001-PLUGIN_EXCLUSION_SYSTEM.md  ← Decision record
    └── PLUGIN_EXCLUSION_SYSTEM.md          ← Technical spec

---

Quick Links

Document	Purpose	Read Time
Plugin Exclusion Guide	Practical how-to's	15 min
Technical Architecture	Deep technical details	30 min
ADR-001	Decision & rationale	20 min

---

Key Concepts

Plugin Exclusion

Mechanism to prevent certain plugins (typically reference implementations) from being included in distributions and installations, while keeping them available for development, testing, and reference purposes.

Key Points:

• Controlled by etc/plugin_registry.toml
• Affects ONLY collection and packaging (not build)
• Used for reference plugins, experimental features, internal tools
• Does NOT prevent building or testing

Distribution Pipeline

Source Code
    ↓ (just build)
Build Output (all plugins)
    ↓ (just collect)
Collection (filtered)
    ↓ (just pack)
Packages (filtered)
    ↓ (install)
User Systems (filtered)

Filtering Points

1. Collection - skips excluded when collecting binaries
2. Packaging - skips excluded when creating archives
3. Configuration - config template doesn't auto-load excluded
4. NOT at Build - all plugins still built for testing

---

System Components

Configuration (etc/plugin_registry.toml)

Source of truth for which plugins are excluded from distributions.

Example:

[distribution]
excluded_plugins = [
    "nu_plugin_example"
]
reason = "Reference implementation"

Collection System (scripts/collect_full_binaries.nu)

Gathers built binaries for distribution, excluding specified plugins.

Functions:

• get_excluded_plugins() - loads exclusion list
• get_workspace_plugins_info() - filters workspace plugins
• get_custom_plugins_info() - filters custom plugins

Packaging System (scripts/create_distribution_packages.nu)

Creates distribution archives, excluding specified plugins.

Functions:

• get_excluded_plugins_dist() - loads exclusion list
• get_plugin_components() - filters plugin components

Installation Configuration (scripts/templates/default_config.nu)

Default Nushell configuration that doesn't auto-load excluded plugins.

---

Testing & Verification

Basic Verification

# Check exclusion list is readable
nu -c "open ./etc/plugin_registry.toml | get distribution.excluded_plugins"

# Verify collection excludes properly
just collect
find distribution -name "*example*"  # Should be empty

# Verify packaging excludes properly
just pack-full
tar -tzf bin_archives/*.tar.gz | grep example  # Should be empty

# Verify builds still include everything
just build
ls nushell/target/release/nu_plugin_example  # Should exist

Release Verification

See Plugin Exclusion Guide - Release Checklist for complete pre-release checklist.

---

Contact & Questions

For questions about:

• Usage: See Plugin Exclusion Guide
• Design: See ADR-001
• Implementation: See Technical Architecture
• Issues: Check the project issue tracker

---

Version Information

Component	Version	Updated
ADR-001	1.0	2025-12-03
Technical Spec	1.0	2025-12-03
User Guide	1.0	2025-12-03
System	v1.0.0	2025-12-03

---

Last Updated: 2025-12-03 Status: Complete & Stable Maintainer: Project Team