# ADR-005: Extension Framework\n\n## Status\n\nAccepted\n\n## Context\n\nProvisioning required a flexible extension mechanism to support:\n\n1. **Custom Providers**: Organizations need to add custom cloud providers beyond AWS, UpCloud, and local\n2. **Custom Task Services**: Users need to integrate proprietary infrastructure services\n3. **Custom Workflows**: Complex organizations require custom orchestration patterns\n4. **Third-Party Integration**: Need to integrate with existing toolchains and systems\n5. **User Customization**: Power users want to extend and modify system behavior\n6. **Plugin Ecosystem**: Enable community contributions and extensions\n7. **Isolation Requirements**: Extensions must not compromise system stability\n8. **Discovery Mechanism**: System must automatically discover and load extensions\n9. **Version Compatibility**: Extensions must work across system version upgrades\n10. **Configuration Integration**: Extensions should integrate with configuration-driven architecture\n\nThe system needed an extension framework that provides:\n\n- Clear extension API and interfaces\n- Safe isolation of extension code\n- Automatic discovery and loading\n- Configuration integration\n- Version compatibility management\n- Developer-friendly extension development patterns\n\n## Decision\n\nImplement a **registry-based extension framework** with structured discovery and isolation:\n\n### Extension Architecture\n\n#### Extension Types\n\n1. **Provider Extensions**: Custom cloud providers and infrastructure backends\n2. **Task Service Extensions**: Custom infrastructure services and components\n3. **Workflow Extensions**: Custom orchestration and deployment patterns\n4. **CLI Extensions**: Additional command-line tools and interfaces\n5. **Template Extensions**: Custom configuration and code generation templates\n6. **Integration Extensions**: External system integrations and connectors\n\n### Extension Structure\n\n```\nextensions/\n├── providers/              # Provider extensions\n│   └── custom-cloud/\n│       ├── extension.toml  # Extension manifest\n│       ├── kcl/           # KCL configuration schemas\n│       ├── nulib/         # Nushell implementation\n│       └── templates/     # Configuration templates\n├── taskservs/             # Task service extensions\n│   └── custom-service/\n│       ├── extension.toml\n│       ├── kcl/\n│       ├── nulib/\n│       └── manifests/     # Kubernetes manifests\n├── workflows/             # Workflow extensions\n│   └── custom-workflow/\n│       ├── extension.toml\n│       └── nulib/\n├── cli/                   # CLI extensions\n│   └── custom-commands/\n│       ├── extension.toml\n│       └── nulib/\n└── integrations/          # Integration extensions\n    └── external-tool/\n        ├── extension.toml\n        └── nulib/\n```\n\n### Extension Manifest (extension.toml)\n\n```\n[extension]\nname = "custom-provider"\nversion = "1.0.0"\ntype = "provider"\ndescription = "Custom cloud provider integration"\nauthor = "Organization Name"\nlicense = "MIT"\nhomepage = "https://github.com/org/custom-provider"\n\n[compatibility]\nprovisioning_version = ">=3.0.0,<4.0.0"\nnushell_version = ">=0.107.0"\nkcl_version = ">=0.11.0"\n\n[dependencies]\nhttp_client = ">=1.0.0"\njson_parser = ">=2.0.0"\n\n[entry_points]\ncli = "nulib/cli.nu"\nprovider = "nulib/provider.nu"\nconfig_schema = "schemas/schema.ncl"\n\n[configuration]\nconfig_prefix = "custom_provider"\nrequired_env_vars = ["CUSTOM_PROVIDER_API_KEY"]\noptional_config = ["custom_provider.region", "custom_provider.timeout"]\n```\n\n### Key Framework Principles\n\n1. **Registry-Based Discovery**: Extensions registered in structured directories\n2. **Manifest-Driven Loading**: Extension capabilities declared in manifest files\n3. **Version Compatibility**: Explicit compatibility declarations and validation\n4. **Configuration Integration**: Extensions integrate with system configuration hierarchy\n5. **Isolation Boundaries**: Extensions isolated from core system and each other\n6. **Standard Interfaces**: Consistent interfaces across extension types\n7. **Development Patterns**: Clear patterns for extension development\n8. **Community Support**: Framework designed for community contributions\n\n## Consequences\n\n### Positive\n\n- **Extensibility**: System can be extended without modifying core code\n- **Community Growth**: Enable community contributions and ecosystem development\n- **Organization Customization**: Organizations can add proprietary integrations\n- **Innovation Support**: New technologies can be integrated via extensions\n- **Isolation Safety**: Extensions cannot compromise system stability\n- **Configuration Consistency**: Extensions integrate with configuration-driven architecture\n- **Development Efficiency**: Clear patterns reduce extension development time\n- **Version Management**: Compatibility system prevents breaking changes\n- **Discovery Automation**: Extensions automatically discovered and loaded\n\n### Negative\n\n- **Complexity Increase**: Additional layer of abstraction and management\n- **Performance Overhead**: Extension loading and isolation adds runtime cost\n- **Testing Complexity**: Must test extension framework and individual extensions\n- **Documentation Burden**: Need comprehensive extension development documentation\n- **Version Coordination**: Extension compatibility matrix requires management\n- **Support Complexity**: Community extensions may require support resources\n\n### Neutral\n\n- **Development Patterns**: Different patterns for extension vs core development\n- **Quality Control**: Community extensions may vary in quality and maintenance\n- **Security Considerations**: Extensions need security review and validation\n- **Dependency Management**: Extension dependencies must be managed carefully\n\n## Alternatives Considered\n\n### Alternative 1: Filesystem-Based Extensions\n\nSimple filesystem scanning for extension discovery.\n**Rejected**: No manifest validation or version compatibility checking. Fragile discovery mechanism.\n\n### Alternative 2: Database-Backed Registry\n\nStore extension metadata in database for discovery.\n**Rejected**: Adds database dependency complexity. Over-engineering for extension discovery needs.\n\n### Alternative 3: Package Manager Integration\n\nUse existing package managers (cargo, npm) for extension distribution.\n**Rejected**: Complicates installation and creates external dependencies. Not suitable for corporate environments.\n\n### Alternative 4: Container-Based Extensions\n\nEach extension runs in isolated container.\n**Rejected**: Too heavy for simple extensions. Complicates development and deployment significantly.\n\n### Alternative 5: Plugin Architecture\n\nTraditional plugin architecture with dynamic loading.\n**Rejected**: Complex for shell-based system. Security and isolation challenges in Nushell environment.\n\n## Implementation Details\n\n### Extension Discovery Process\n\n1. **Directory Scanning**: Scan extension directories for manifest files\n2. **Manifest Validation**: Parse and validate extension manifest\n3. **Compatibility Check**: Verify version compatibility requirements\n4. **Dependency Resolution**: Resolve extension dependencies\n5. **Configuration Integration**: Merge extension configuration schemas\n6. **Entry Point Registration**: Register extension entry points with system\n\n### Extension Loading Lifecycle\n\n```\n# Extension discovery and validation\nprovisioning extension discover\nprovisioning extension validate --extension custom-provider\n\n# Extension activation and configuration\nprovisioning extension enable custom-provider\nprovisioning extension configure custom-provider\n\n# Extension usage\nprovisioning provider list  # Shows custom providers\nprovisioning server create --provider custom-provider\n\n# Extension management\nprovisioning extension disable custom-provider\nprovisioning extension update custom-provider\n```\n\n### Configuration Integration\n\nExtensions integrate with hierarchical configuration system:\n\n```\n# System configuration includes extension settings\n[custom_provider]\napi_endpoint = "https://api.custom-cloud.com"\nregion = "us-west-1"\ntimeout = 30\n\n# Extension configuration follows same hierarchy rules\n# System defaults → User config → Environment config → Runtime\n```\n\n### Security and Isolation\n\n- **Sandboxed Execution**: Extensions run in controlled environment\n- **Permission Model**: Extensions declare required permissions in manifest\n- **Code Review**: Community extensions require review process\n- **Digital Signatures**: Extensions can be digitally signed for authenticity\n- **Audit Logging**: Extension usage tracked in system audit logs\n\n### Development Support\n\n- **Extension Templates**: Scaffold new extensions from templates\n- **Development Tools**: Testing and validation tools for extension developers\n- **Documentation Generation**: Automatic documentation from extension manifests\n- **Integration Testing**: Framework for testing extensions with core system\n\n## Extension Development Patterns\n\n### Provider Extension Pattern\n\n```\n# extensions/providers/custom-cloud/nulib/provider.nu\nexport def list-servers [] -> table {\n    http get $"($config.custom_provider.api_endpoint)/servers"\n    | from json\n    | select name status region\n}\n\nexport def create-server [name: string, config: record] -> record {\n    let payload = {\n        name: $name,\n        instance_type: $config.plan,\n        region: $config.zone\n    }\n\n    http post $"($config.custom_provider.api_endpoint)/servers" $payload\n    | from json\n}\n```\n\n### Task Service Extension Pattern\n\n```\n# extensions/taskservs/custom-service/nulib/service.nu\nexport def install [server: string] -> nothing {\n    let manifest_data = open ./manifests/deployment.yaml\n    | str replace "{{server}}" $server\n\n    kubectl apply --server $server --data $manifest_data\n}\n\nexport def uninstall [server: string] -> nothing {\n    kubectl delete deployment custom-service --server $server\n}\n```\n\n## References\n\n- Workspace Isolation (ADR-003)\n- Configuration System Architecture (ADR-002)\n- Hybrid Architecture Integration (ADR-004)\n- Community Extension Guidelines\n- Extension Security Framework\n- Extension Development Documentation
