[Spec] Azure Developer CLI Extension Framework Enhancements Adoption

[jongio]

Summary

Adopt recent Azure Developer CLI extension framework enhancements across azd-exec, azd-app, and azd-core to improve observability, debugging, reliability, and developer experience.

Spec: docs/specs/azd-framework-enhancements/spec.md

Key Enhancements

1. Distributed Tracing - OpenTelemetry integration with W3C Trace Context
2. Structured Error Handling - Unified error model with origin tracking
3. Interactive Extension Support - TUI/interactive mode for extensions
4. ServiceContext in Lifecycle Events - Enhanced event context with build artifacts
5. Automatic Event Handler Cleanup - Context-based lifecycle management
6. WaitForDebugger Export - Public debugger attachment API
7. Additional Properties Support - Extension-specific config in azure.yaml

Goals

1. ✅ Enhance Observability - Add distributed tracing to azd-exec and azd-app
2. ✅ Improve Error Handling - Adopt structured error model across all extensions
3. ✅ Better Developer Experience - Export debugger support, interactive mode
4. ✅ Leverage Event Context - Utilize ServiceContext in azd-app lifecycle handlers
5. ✅ Improve Reliability - Auto cleanup, duplicate prevention
6. ✅ Enable Extensibility - Support additional properties for extension config
7. ✅ Identify Common Code Opportunities - Extract shared utilities and patterns to azd-core for reuse across extensions

Implementation Plan

Phase 1: Foundation (Week 1) - P0

• Add structured error package to azd-core
• Update azd-exec to use azdext.NewContext() for tracing
• Update azd-app to use azdext.NewContext() for tracing
• Add WaitForDebugger to both extensions' listen commands
• Update go.mod dependencies if needed
• Identify common patterns/utilities that could move to azd-core

Phase 2: Error Handling (Week 2) - P1

• Refactor azd-exec error handling to use structured errors
• Refactor azd-app error handling to use structured errors
• Add error origin categorization throughout
• Add tests for error handling
• Extract common error handling utilities to azd-core

Phase 3: Event Enhancements (Week 2) - P1

• Update azd-app lifecycle handlers to use ServiceContext
• Enhance dashboard to show artifact information
• Enhance notifications with build/package details
• Add tests for event context usage
• Identify event handling patterns that could be shared

Phase 4: Azure SDK Correlation (Week 3) - P2

• Add correlation policy to azd-app Azure clients
• Verify trace correlation in logs command
• Verify trace correlation in health checks
• Add trace context to MCP server operations
• Extract Azure SDK helpers/policies to azd-core if reusable

Phase 5: Config Extensibility (Week 3-4) - P2

• Design azd-app config schema for azure.yaml
• Implement config reading in relevant commands
• Update documentation with config examples
• Add tests for config extraction
• Move config parsing utilities to azd-core for extension reuse

Phase 6: Testing & Documentation (Week 4) - P1

• Integration tests for tracing
• Integration tests for error handling
• Update CONTRIBUTING.md with debugging instructions
• Update README.md with tracing/config features
• Add examples directory with azure.yaml samples
• Document azd-core utilities for extension developers

Ongoing: Code Consolidation Analysis

As we implement each phase, actively look for:

• Duplicate code between azd-exec and azd-app that could be shared
• Common patterns (config parsing, Azure SDK setup, error handling)
• Utility functions that would benefit multiple extensions
• Testing helpers that could be reused
• Documentation patterns and helper code

Candidates for azd-core:

• Config extraction helpers (AdditionalProperties parsing)
• Azure SDK client factory with tracing/correlation
• Common error handling/categorization utilities
• Extension lifecycle helpers
• Test fixtures and utilities

Benefits

• End-to-end trace visibility from azd through extensions to Azure services
• Consistent error categorization with better telemetry
• Improved debugging experience with standardized debugger attachment
• Richer context in lifecycle events
• No memory leaks from automatic handler cleanup
• Extension configuration lives with project config in azure.yaml
• Reduced duplication and improved maintainability via shared azd-core utilities
• Faster extension development with reusable components

Dependencies

• Requires azd >= 1.22.0
• Impacts: azd-exec, azd-app, azd-core repositories