Azure / Azure/azure-dev

Custom Command Discoverability

Open
#6,228 0 comments 0 reactions 0 assignees View on GitHub
area/ext-framework area/extensions discoverability feature
Dominant language
Go
Stars
569
Forks
364
Avg merge
2d 19h
Merged PRs (30d)
136

Description

## Description

Implement a programmatic mechanism for discovering and listing all commands available from installed extensions, addressing the current limitation where command discovery relies solely on static "examples" in the extension manifest.

## Current Limitations

- `azd` has no built-in discovery process to understand what commands are available for a given extension
- Extension authors can provide "examples" in the extension manifest, but:
- May not be a comprehensive list of all available commands
- Can drift from actual implementation as extension evolves
- Not easily discoverable or parseable by users or tooling
- No standardized format for command metadata

## Acceptance Criteria

- Programmatic API for extensions to expose available commands and metadata
- Command discovery mechanism accessible via `azd` CLI (e.g., `azd extension commands `)
- Standardized command metadata schema including:
- Command name and aliases
- Description and usage
- Parameters and flags
- Examples
- Deprecation status
- Integration with `azd help` system to surface extension commands
- Backward compatibility with existing manifest-based examples

## Proposed Solutions

### 1. Command Registration API
- Extensions register commands programmatically on load
- Runtime introspection of registered commands
- Support for dynamic command discovery

### 2. Enhanced Manifest Schema
- Structured commands section in extension manifest
- JSON schema validation for command definitions
- Auto-generation of command metadata from extension code

### 3. CLI Discovery Commands
- `azd extension commands ` - List all commands for an extension
- `azd extension commands --all` - List commands from all installed extensions
- `azd help ` - Show detailed help for extension command

## Related Issues

- #4989 (Extension Developer Documentation) - Would include command registration patterns
- #5767 (Extension Enhancements Epic) - Core framework enhancement

## Benefits

- Improved developer and user experience discovering extension capabilities
- Reduces maintenance burden (no manual example updates)
- Enables tooling integration (IDE autocomplete, documentation generation)
- Better command namespace conflict detection
- Foundation for extension marketplace/catalog features

## Additional Considerations

- Consider integration with shell completion (bash, zsh, PowerShell)
- Support for command deprecation and versioning
- Telemetry on command usage for extension authors
- Potential for AI-assisted command discovery (GitHub Copilot integration)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.