feat: gate azd tool command group behind alpha feature flag (#8111)

* Gate 'azd tool' command group and middleware behind alpha feature flag

Register a new 'tool' alpha feature in alpha_features.yaml and gate:
- Command registration in toolActions() (tool.go/root.go)
- ToolFirstRunMiddleware (tool_first_run.go)
- ToolUpdateCheckMiddleware (tool_update_check.go)

Users enable via: azd config set alpha.tool on
Or env var: AZD_ALPHA_ENABLE_TOOL=true

Tests updated to set AZD_ALPHA_ENABLE_TOOL=true where needed, with
new test cases verifying the feature is hidden when the flag is off.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: address code review findings for alpha feature flag

- Add debug logging when user config fails to load for alpha gating
- Move alpha check to call site in root.go for clearer nil-safety
- Verify YAML description formatting

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: wbreza

.github-pr-body.md

@@ -28,6 +28,7 @@ func TestFigSpec(t *testing.T) {
 	t.Setenv("AZD_CONFIG_DIR", configDir)
 	t.Setenv("AZURE_DEV_COLLECT_TELEMETRY", "no")
 	t.Setenv("AZD_SKIP_FIRST_RUN", "true")
+	t.Setenv("AZD_ALPHA_ENABLE_TOOL", "true")
 
 	cli := azdcli.NewCLI(t)
 

cli/azd/cmd/figspec_test.go

@@ -15,6 +15,7 @@ import (
 	"github.com/azure/azure-dev/cli/azd/cmd/actions"
 	"github.com/azure/azure-dev/cli/azd/internal"
 	"github.com/azure/azure-dev/cli/azd/internal/tracing/resource"
+	"github.com/azure/azure-dev/cli/azd/pkg/alpha"
 	"github.com/azure/azure-dev/cli/azd/pkg/config"
 	"github.com/azure/azure-dev/cli/azd/pkg/input"
 	"github.com/azure/azure-dev/cli/azd/pkg/output"
@@ -35,6 +36,7 @@ const envKeySkipFirstRun = "AZD_SKIP_FIRST_RUN"
 // installed Azure development tools and optionally offers to
 // install any missing recommended tools.
 type ToolFirstRunMiddleware struct {
+	alphaManager  *alpha.FeatureManager
 	configManager config.UserConfigManager
 	console       input.Console
 	manager       *tool.Manager
@@ -43,12 +45,14 @@ type ToolFirstRunMiddleware struct {
 
 // NewToolFirstRunMiddleware creates a new [ToolFirstRunMiddleware].
 func NewToolFirstRunMiddleware(
+	alphaManager *alpha.FeatureManager,
 	configManager config.UserConfigManager,
 	console input.Console,
 	manager *tool.Manager,
 	options *internal.GlobalCommandOptions,
 ) Middleware {
 	return &ToolFirstRunMiddleware{
+		alphaManager:  alphaManager,
 		configManager: configManager,
 		console:       console,
 		manager:       manager,
@@ -61,6 +65,11 @@ func NewToolFirstRunMiddleware(
 // always delegates to nextFn so the user's intended command is
 // never blocked.
 func (m *ToolFirstRunMiddleware) Run(ctx context.Context, nextFn NextFn) (*actions.ActionResult, error) {
+	// Skip when the tool alpha feature is not enabled.
+	if !m.alphaManager.IsEnabled(tool.FeatureAlphaTool) {
+		return nextFn(ctx)
+	}
+
 	// Skip for child actions (e.g. workflow steps).
 	if IsChildAction(ctx) {
 		return nextFn(ctx)

cli/azd/cmd/middleware/tool_first_run.go

@@ -10,6 +10,7 @@ import (
 
 	"github.com/azure/azure-dev/cli/azd/cmd/actions"
 	"github.com/azure/azure-dev/cli/azd/internal"
+	"github.com/azure/azure-dev/cli/azd/pkg/alpha"
 	"github.com/azure/azure-dev/cli/azd/pkg/config"
 	"github.com/azure/azure-dev/cli/azd/test/mocks/mockinput"
 	"github.com/stretchr/testify/assert"
@@ -58,6 +59,7 @@ func passthroughNext(called *bool) NextFn {
 func TestToolFirstRunMiddleware_SkipConditions(t *testing.T) {
 	// These tests modify env vars via t.Setenv so they cannot be
 	// parallel with each other or with tests that read the same vars.
+	t.Setenv("AZD_ALPHA_ENABLE_TOOL", "true")
 
 	tests := []struct {
 		name     string
@@ -141,6 +143,7 @@ func TestToolFirstRunMiddleware_SkipConditions(t *testing.T) {
 			ucm := &mockUserConfigManager{cfg: cfg}
 
 			m := &ToolFirstRunMiddleware{
+				alphaManager:  alpha.NewFeaturesManagerWithConfig(config.NewEmptyConfig()),
 				configManager: ucm,
 				console:       console,
 				manager:       nil, // not needed for skip paths
@@ -177,13 +180,15 @@ func TestToolFirstRunMiddleware_TriggersWhenNoSkip(t *testing.T) {
 	clearCIVars(t)
 	t.Setenv(envKeySkipFirstRun, "")
 	os.Unsetenv(envKeySkipFirstRun)
+	t.Setenv("AZD_ALPHA_ENABLE_TOOL", "true")
 
 	console := mockinput.NewMockConsole()
 	cfg := config.NewEmptyConfig()
 	opts := &internal.GlobalCommandOptions{}
 	ucm := &mockUserConfigManager{cfg: cfg}
 
 	m := &ToolFirstRunMiddleware{
+		alphaManager:  alpha.NewFeaturesManagerWithConfig(config.NewEmptyConfig()),
 		configManager: ucm,
 		console:       console,
 		manager:       nil, // runFirstRunExperience will fail at prompt
@@ -205,3 +210,35 @@ func TestToolFirstRunMiddleware_TriggersWhenNoSkip(t *testing.T) {
 	assert.NotEmpty(t, console.Output(),
 		"triggered first-run experience should produce console output")
 }
+
+// TestToolFirstRunMiddleware_SkipsWhenAlphaDisabled verifies that the
+// middleware is a no-op when the tool alpha feature is not enabled.
+func TestToolFirstRunMiddleware_SkipsWhenAlphaDisabled(t *testing.T) {
+	clearCIVars(t)
+	t.Setenv(envKeySkipFirstRun, "")
+	os.Unsetenv(envKeySkipFirstRun)
+	t.Setenv("AZD_ALPHA_ENABLE_TOOL", "false")
+
+	console := mockinput.NewMockConsole()
+	cfg := config.NewEmptyConfig()
+	opts := &internal.GlobalCommandOptions{}
+	ucm := &mockUserConfigManager{cfg: cfg}
+
+	m := &ToolFirstRunMiddleware{
+		alphaManager:  alpha.NewFeaturesManagerWithConfig(config.NewEmptyConfig()),
+		configManager: ucm,
+		console:       console,
+		manager:       nil,
+		options:       opts,
+	}
+
+	nextCalled := false
+	result, err := m.Run(t.Context(), passthroughNext(&nextCalled))
+
+	require.NoError(t, err)
+	require.NotNil(t, result)
+	assert.True(t, nextCalled,
+		"nextFn must always be called even when alpha is disabled")
+	assert.Empty(t, console.Output(),
+		"alpha-disabled should skip the first-run experience entirely")
+}

cli/azd/cmd/middleware/tool_first_run_test.go

@@ -14,6 +14,7 @@ import (
 	"github.com/azure/azure-dev/cli/azd/cmd/actions"
 	"github.com/azure/azure-dev/cli/azd/internal"
 	"github.com/azure/azure-dev/cli/azd/internal/tracing/resource"
+	"github.com/azure/azure-dev/cli/azd/pkg/alpha"
 	"github.com/azure/azure-dev/cli/azd/pkg/input"
 	"github.com/azure/azure-dev/cli/azd/pkg/output"
 	"github.com/azure/azure-dev/cli/azd/pkg/tool"
@@ -25,6 +26,7 @@ import (
 // interactive and the current command is not a tool-management
 // subcommand.
 type ToolUpdateCheckMiddleware struct {
+	alphaManager  *alpha.FeatureManager
 	manager       *tool.Manager
 	console       input.Console
 	options       *Options
@@ -34,12 +36,14 @@ type ToolUpdateCheckMiddleware struct {
 // NewToolUpdateCheckMiddleware creates a new [ToolUpdateCheckMiddleware].
 // All dependencies are resolved by the IoC container.
 func NewToolUpdateCheckMiddleware(
+	alphaManager *alpha.FeatureManager,
 	manager *tool.Manager,
 	console input.Console,
 	options *Options,
 	globalOptions *internal.GlobalCommandOptions,
 ) Middleware {
 	return &ToolUpdateCheckMiddleware{
+		alphaManager:  alphaManager,
 		manager:       manager,
 		console:       console,
 		options:       options,
@@ -52,6 +56,11 @@ func NewToolUpdateCheckMiddleware(
 // completes it triggers a background update check when the configured
 // check interval has elapsed.
 func (m *ToolUpdateCheckMiddleware) Run(ctx context.Context, nextFn NextFn) (*actions.ActionResult, error) {
+	// Skip when the tool alpha feature is not enabled.
+	if !m.alphaManager.IsEnabled(tool.FeatureAlphaTool) {
+		return nextFn(ctx)
+	}
+
 	// Skip all notification and background-check logic for child
 	// actions (e.g. workflow steps invoked by a parent command).
 	if !IsChildAction(ctx) {

cli/azd/cmd/middleware/tool_update_check.go

@@ -11,6 +11,7 @@ import (
 
 	"github.com/azure/azure-dev/cli/azd/cmd/actions"
 	"github.com/azure/azure-dev/cli/azd/internal"
+	"github.com/azure/azure-dev/cli/azd/pkg/alpha"
 	"github.com/azure/azure-dev/cli/azd/pkg/config"
 	"github.com/azure/azure-dev/cli/azd/pkg/tool"
 	"github.com/azure/azure-dev/cli/azd/test/mocks/mockinput"
@@ -39,6 +40,7 @@ func newUpdateCheckMiddleware(
 	}
 
 	return &ToolUpdateCheckMiddleware{
+		alphaManager:  alpha.NewFeaturesManagerWithConfig(config.NewEmptyConfig()),
 		manager:       manager,
 		console:       console,
 		options:       opts,
@@ -51,6 +53,8 @@ func newUpdateCheckMiddleware(
 // ---------------------------------------------------------------------------
 
 func TestToolUpdateCheckMiddleware_SkipNotification(t *testing.T) {
+	t.Setenv("AZD_ALPHA_ENABLE_TOOL", "true")
+
 	tests := []struct {
 		name  string
 		setup func(
@@ -147,6 +151,7 @@ func TestToolUpdateCheckMiddleware_SkipNotification(t *testing.T) {
 
 func TestToolUpdateCheckMiddleware_ChildAction(t *testing.T) {
 	clearCIVars(t)
+	t.Setenv("AZD_ALPHA_ENABLE_TOOL", "true")
 
 	console := mockinput.NewMockConsole()
 	m := newUpdateCheckMiddleware(
@@ -175,6 +180,7 @@ func TestToolUpdateCheckMiddleware_NotificationGating(t *testing.T) {
 	clearCIVars(t)
 	t.Setenv(envKeySkipFirstRun, "")
 	os.Unsetenv(envKeySkipFirstRun)
+	t.Setenv("AZD_ALPHA_ENABLE_TOOL", "true")
 
 	console := mockinput.NewMockConsole()
 	cfg := config.NewEmptyConfig()
@@ -229,6 +235,7 @@ func TestToolUpdateCheckMiddleware_BackgroundCheckSkippedWhenCI(
 	// early and never calls manager.ShouldCheckForUpdates.
 	clearCIVars(t)
 	t.Setenv("CI", "1")
+	t.Setenv("AZD_ALPHA_ENABLE_TOOL", "true")
 
 	console := mockinput.NewMockConsole()
 
@@ -259,6 +266,7 @@ func TestToolUpdateCheckMiddleware_BackgroundCheckSkippedByEnvVar(
 ) {
 	clearCIVars(t)
 	t.Setenv(envKeySkipFirstRun, "true")
+	t.Setenv("AZD_ALPHA_ENABLE_TOOL", "true")
 
 	console := mockinput.NewMockConsole()
 
@@ -312,6 +320,32 @@ func TestToolUpdateCheckMiddleware_IsToolCommand(t *testing.T) {
 	}
 }
 
+// TestToolUpdateCheckMiddleware_SkipsWhenAlphaDisabled verifies that
+// the middleware is a no-op when the tool alpha feature is not enabled.
+func TestToolUpdateCheckMiddleware_SkipsWhenAlphaDisabled(t *testing.T) {
+	clearCIVars(t)
+	t.Setenv("AZD_ALPHA_ENABLE_TOOL", "false")
+	t.Setenv(envKeySkipFirstRun, "")
+	os.Unsetenv(envKeySkipFirstRun)
+
+	console := mockinput.NewMockConsole()
+	m := newUpdateCheckMiddleware(
+		nil, console,
+		&Options{CommandPath: "azd provision"},
+		&internal.GlobalCommandOptions{},
+	)
+
+	nextCalled := false
+	result, err := m.Run(t.Context(), passthroughNext(&nextCalled))
+
+	require.NoError(t, err)
+	require.NotNil(t, result)
+	assert.True(t, nextCalled,
+		"nextFn must always be called even when alpha is disabled")
+	assert.Empty(t, console.Output(),
+		"alpha-disabled should skip update check entirely")
+}
+
 // ---------------------------------------------------------------------------
 // TestToolUpdateCheckMiddleware_AlwaysCallsNext
 // ---------------------------------------------------------------------------
@@ -320,6 +354,7 @@ func TestToolUpdateCheckMiddleware_AlwaysCallsNext(t *testing.T) {
 	clearCIVars(t)
 	// Skip background check so the nil manager is not accessed.
 	t.Setenv(envKeySkipFirstRun, "true")
+	t.Setenv("AZD_ALPHA_ENABLE_TOOL", "true")
 
 	console := mockinput.NewMockConsole()
 	console.SetNoPromptMode(true) // triggers notification skip

cli/azd/cmd/middleware/tool_update_check_test.go

@@ -17,10 +17,13 @@ import (
 
 	// Importing for infrastructure provider plugin registrations
 
+	"github.com/azure/azure-dev/cli/azd/pkg/alpha"
 	"github.com/azure/azure-dev/cli/azd/pkg/azd"
+	"github.com/azure/azure-dev/cli/azd/pkg/config"
 	"github.com/azure/azure-dev/cli/azd/pkg/extensions"
 	"github.com/azure/azure-dev/cli/azd/pkg/ioc"
 	"github.com/azure/azure-dev/cli/azd/pkg/platform"
+	"github.com/azure/azure-dev/cli/azd/pkg/tool"
 
 	"github.com/azure/azure-dev/cli/azd/internal"
 	"github.com/azure/azure-dev/cli/azd/internal/cmd"
@@ -196,7 +199,13 @@ func newRootCmd(
 	hooksActions(root)
 	mcpActions(root)
 	copilotActions(root)
-	toolActions(root)
+
+	// Create a FeatureManager for command-tree gating.
+	// User config is loaded best-effort; env vars (AZD_ALPHA_ENABLE_TOOL) always work.
+	alphaManager := newAlphaManagerForCommandTree()
+	if alphaManager.IsEnabled(tool.FeatureAlphaTool) {
+		toolActions(root)
+	}
 
 	root.Add("version", &actions.ActionDescriptorOptions{
 		Command: &cobra.Command{
@@ -563,6 +572,20 @@ var workflowCommands = map[string]struct{}{
 	"restore":   {},
 }
 
+// newAlphaManagerForCommandTree creates a FeatureManager for use during
+// command-tree construction (before DI is available).  It loads the
+// user config best-effort so that `azd config set alpha.tool on` works;
+// env-var overrides (AZD_ALPHA_ENABLE_TOOL) always work regardless.
+func newAlphaManagerForCommandTree() *alpha.FeatureManager {
+	ucm := config.NewUserConfigManager(config.NewFileConfigManager(config.NewManager()))
+	cfg, err := ucm.Load()
+	if err != nil {
+		log.Printf("warning: failed to load user config for alpha feature gating: %v", err)
+		cfg = config.NewEmptyConfig()
+	}
+	return alpha.NewFeaturesManagerWithConfig(cfg)
+}
+
 // isWorkflowCommand reports whether the command is a primary workflow
 // command where a first-run tool check adds value.
 func isWorkflowCommand(descriptor *actions.ActionDescriptor) bool {

cli/azd/cmd/root.go

@@ -23,6 +23,7 @@ import (
 )
 
 // toolActions registers the "azd tool" command group and all of its subcommands.
+// The caller is responsible for gating on the "tool" alpha feature flag.
 func toolActions(root *actions.ActionDescriptor) *actions.ActionDescriptor {
 	toolCmd := &cobra.Command{
 		Use:   "tool",