# 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](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md)

**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](./PLUGIN_EXCLUSION_SYSTEM.md)

**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](../PLUGIN_EXCLUSION_GUIDE.md)

**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)](../PLUGIN_EXCLUSION_GUIDE.md#for-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)](../PLUGIN_EXCLUSION_GUIDE.md#for-developers)
Then read: [Technical Architecture](./PLUGIN_EXCLUSION_SYSTEM.md)
- How to exclude your plugin during development
- How the filtering system works
- Implementation details

**📦 Release Managers**:
Start with: [Plugin Exclusion Guide - Release Checklist](../PLUGIN_EXCLUSION_GUIDE.md#for-release-managers)
Then read: [ADR-001](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md)
- Pre-release verification steps
- How to test exclusions
- Decision rationale for documentation

**🔧 Maintainers/Architects**:
Start with: [ADR-001](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md)
Then read: [Technical Architecture](./PLUGIN_EXCLUSION_SYSTEM.md)
- 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](../PLUGIN_EXCLUSION_GUIDE.md#task-1-add-a-plugin-to-exclusion-list)

**"I want to remove a plugin from exclusion"**:
→ [Plugin Exclusion Guide - Task 2](../PLUGIN_EXCLUSION_GUIDE.md#task-2-remove-a-plugin-from-exclusion-list)

**"I need to understand the workflow"**:
→ [Plugin Exclusion Guide - Task 4](../PLUGIN_EXCLUSION_GUIDE.md#task-4-understand-distribution-workflow)

**"Something isn't working"**:
→ [Plugin Exclusion Guide - Troubleshooting](../PLUGIN_EXCLUSION_GUIDE.md#troubleshooting)

**"I need to extend the system"**:
→ [Technical Architecture - Future Enhancements](./PLUGIN_EXCLUSION_SYSTEM.md#future-enhancements)

**"I need to integrate with CI/CD"**:
→ [Plugin Exclusion Guide - CI/CD Integration](../PLUGIN_EXCLUSION_GUIDE.md#integration-with-cicd)

---

## 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](../PLUGIN_EXCLUSION_GUIDE.md) | Practical how-to's | 15 min |
| [Technical Architecture](./PLUGIN_EXCLUSION_SYSTEM.md) | Deep technical details | 30 min |
| [ADR-001](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md) | 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**:
```toml
[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
```bash
# 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](../PLUGIN_EXCLUSION_GUIDE.md#for-release-managers) for complete pre-release checklist.

---

## Contact & Questions

For questions about:
- **Usage**: See [Plugin Exclusion Guide](../PLUGIN_EXCLUSION_GUIDE.md)
- **Design**: See [ADR-001](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md)
- **Implementation**: See [Technical Architecture](./PLUGIN_EXCLUSION_SYSTEM.md)
- **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