Add lstk az start-interception and stop-interception commands (#336)

Author: carole-lavillonniere

CLAUDE.md

@@ -72,11 +72,14 @@ Use `lstk setup <emulator>` to set up CLI integration for an emulator type:
 - `lstk setup aws` — Sets up AWS CLI profile in `~/.aws/config` and `~/.aws/credentials`
 - `lstk setup azure` — Prepares an isolated Azure CLI config dir (under the lstk config dir, via `AZURE_CONFIG_DIR`): registers a custom Azure cloud (`LocalStack`) whose endpoints point at the LocalStack Azure emulator, activates it, disables Azure CLI instance discovery and telemetry, and performs a one-time dummy service-principal login. The user's global `~/.azure` is left untouched. Requires the `az` CLI and a running Azure emulator.
 - `lstk az <args>` — Runs `az <args>` against that isolated config dir, so the Azure CLI talks to LocalStack for Azure service URLs and to the real internet for everything else (extension downloads, etc.).
+- `lstk az start-interception` / `lstk az stop-interception` — Opt-in second mode: instead of the isolated dir, these mutate the user's **global** `~/.azure` so plain `az` (any terminal/script) targets LocalStack, then switch back. `start-interception` runs the same register → activate → `instance_discovery=false` → dummy-login flow against the global config (but does not touch global telemetry/survey prefs) and is independent of `lstk setup azure`. `stop-interception` switches the active cloud back to `AzureCloud` (override with `--cloud <name>`, validated against the live `az cloud list`) and re-enables instance discovery — but only if `LocalStack` is still the active cloud, to avoid clobbering an unrelated selection.
 
 This naming avoids AWS-specific "profile" terminology and uses a clear verb for mutation operations.
 The deprecated `lstk config profile` command still works but points users to `lstk setup aws`.
 
-Azure CLI integration deliberately mirrors `lstk aws`, not azlocal's `start-interception` (which globally mutates `~/.azure`). The Azure CLI has no `--endpoint-url`/`--profile`, so the only isolation knob is `AZURE_CONFIG_DIR`. Inside that isolated dir we register a custom cloud whose endpoints point at `https://azure.localhost.localstack.cloud:4566`, so `az` makes direct calls to LocalStack for Azure services (no HTTP(S) forward proxy in front of `az`). `core.instance_discovery=false` is required because `az` does not recognise the LocalStack host as a real Azure cloud. Adding a new Azure service that needs its own endpoint in `az`'s cloud config means extending the map in `internal/azureconfig/azureconfig.go::BuildCloudConfig`.
+The default `lstk az <args>` mode mirrors `lstk aws`: the Azure CLI has no `--endpoint-url`/`--profile`, so the only isolation knob is `AZURE_CONFIG_DIR`. Inside that isolated dir we register a custom cloud whose endpoints point at `https://azure.localhost.localstack.cloud:4566`, so `az` makes direct calls to LocalStack for Azure services (no HTTP(S) forward proxy in front of `az`). `core.instance_discovery=false` is required because `az` does not recognise the LocalStack host as a real Azure cloud. Adding a new Azure service that needs its own endpoint in `az`'s cloud config means extending the map in `internal/azureconfig/azureconfig.go::BuildCloudConfig`.
+
+`lstk az start-interception`/`stop-interception` additionally offer azlocal's global pattern (the same cloud registration applied to `~/.azure` rather than the isolated dir), so existing `az` scripts run unmodified against LocalStack. This is intentionally documented as optional because it mutates global state; prefer the isolated `lstk az <args>` mode unless a script must invoke plain `az`. The interception domain logic lives in `internal/azureconfig/interception.go` and reuses the shared `registerLocalStackCloud` helper; the command wiring (subcommands under `az` plus the shared `azPreflight` checks) is in `cmd/az.go`.
 
 Environment variables:
 - `LOCALSTACK_AUTH_TOKEN` - Auth token (skips browser login if set)

README.md

@@ -109,6 +109,16 @@ lstk az group list
 
 `lstk setup azure` registers a custom Azure cloud — pointing at LocalStack's endpoints — inside an isolated `AZURE_CONFIG_DIR`, so your global `~/.azure` keeps pointing at real Azure.
 
+To run existing `az` scripts unmodified against LocalStack, you can instead redirect your **global** Azure CLI:
+
+```bash
+lstk az start-interception   # plain `az` now targets LocalStack
+az group list                # hits LocalStack, no `lstk` prefix needed
+lstk az stop-interception    # back to real Azure (use --cloud to pick another cloud)
+```
+
+This is optional and changes global state affecting every `az` invocation until you stop it; prefer `lstk az <command>` unless a script must call plain `az`.
+
 You can also point `lstk` at a specific config file for any command:
 
 ```bash
@@ -255,6 +265,10 @@ lstk setup azure
 # Run Azure CLI commands against LocalStack
 lstk az group list
 
+# Or redirect your global `az` so existing scripts hit LocalStack unmodified
+lstk az start-interception
+lstk az stop-interception
+
 # Save emulator state to a local file
 lstk snapshot save ./my-snapshot.snapshot
 

cmd/az.go

@@ -1,6 +1,7 @@
 package cmd
 
 import (
+	"context"
 	"fmt"
 	"io"
 	"os"
@@ -15,45 +16,30 @@ import (
 	"github.com/localstack/lstk/internal/output"
 	"github.com/localstack/lstk/internal/runtime"
 	"github.com/localstack/lstk/internal/terminal"
+	"github.com/localstack/lstk/internal/ui"
 	"github.com/spf13/cobra"
 )
 
 func newAzCmd(cfg *env.Env) *cobra.Command {
-	return &cobra.Command{
+	cmd := &cobra.Command{
 		Use:   "az [args...]",
 		Short: "Run Azure CLI commands against LocalStack",
 		Long: `Run Azure CLI commands against the LocalStack Azure emulator.
 
-Runs 'az <args>' with an isolated AZURE_CONFIG_DIR in which a custom Azure cloud is registered against LocalStack's endpoints, so your global ~/.azure configuration is left untouched and plain 'az' commands keep talking to real Azure.
+'lstk az <args>' runs 'az <args>' with an isolated AZURE_CONFIG_DIR in which a custom Azure cloud is registered against LocalStack's endpoints, so your global ~/.azure configuration is left untouched and plain 'az' commands keep talking to real Azure. Run 'lstk setup azure' once before using this mode.
 
-Run 'lstk setup azure' once before using this command.
+Alternatively, 'lstk az start-interception' redirects your global 'az' to LocalStack so existing scripts run unmodified, and 'lstk az stop-interception' switches back. Interception changes global state and is optional — prefer 'lstk az <args>' unless you specifically need plain 'az' to target LocalStack.
 
 Examples:
   lstk az group list
-  lstk az storage account list`,
+  lstk az storage account list
+  lstk az start-interception
+  lstk az stop-interception`,
 		DisableFlagParsing: true,
 		PreRunE:            initConfig(nil),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			sink := output.NewPlainSink(os.Stdout)
 
-			rt, err := runtime.NewDockerRuntime(cfg.DockerHost)
-			if err != nil {
-				return err
-			}
-
-			appCfg, err := config.Get()
-			if err != nil {
-				return fmt.Errorf("failed to get config: %w", err)
-			}
-
-			azureContainer := config.ContainerConfig{Type: config.EmulatorAzure, Port: config.DefaultPort}
-			for _, c := range appCfg.Containers {
-				if c.Type == config.EmulatorAzure {
-					azureContainer = c
-					break
-				}
-			}
-
 			configDir, err := config.ConfigDir()
 			if err != nil {
 				return fmt.Errorf("failed to resolve config directory: %w", err)
@@ -69,45 +55,8 @@ Examples:
 				return output.NewSilentError(fmt.Errorf("azure CLI integration not set up"))
 			}
 
-			if err := azurecli.CheckInstalled(); err != nil {
-				sink.Emit(output.ErrorEvent{
-					Title:   "az CLI not found in PATH",
-					Actions: []output.ErrorAction{{Label: "Install Azure CLI:", Value: azurecli.InstallURL}},
-				})
-				return output.NewSilentError(err)
-			}
-
-			if err := rt.IsHealthy(cmd.Context()); err != nil {
-				rt.EmitUnhealthyError(sink, err)
-				return output.NewSilentError(fmt.Errorf("runtime not healthy: %w", err))
-			}
-
-			runningName, err := container.ResolveRunningContainerName(cmd.Context(), rt, azureContainer)
-			if err != nil {
-				return fmt.Errorf("checking emulator status: %w", err)
-			}
-			if runningName == "" {
-				sink.Emit(output.ErrorEvent{
-					Title: fmt.Sprintf("%s is not running", azureContainer.DisplayName()),
-					Actions: []output.ErrorAction{
-						{Label: "Start LocalStack:", Value: "lstk"},
-						{Label: "See help:", Value: "lstk -h"},
-					},
-				})
-				return output.NewSilentError(fmt.Errorf("%s is not running", azureContainer.Name()))
-			}
-
-			_, dnsOK := endpoint.ResolveHost(cmd.Context(), azureContainer.Port, cfg.LocalStackHost)
-			if !dnsOK {
-				sink.Emit(output.ErrorEvent{
-					Title: "DNS resolution required for 'lstk az'",
-					Actions: []output.ErrorAction{
-						{Label: "Note:", Value: "Could not resolve *." + endpoint.Hostname + " to 127.0.0.1."},
-						{Label: "Why:", Value: "the Azure emulator serves endpoints under *." + endpoint.Hostname + ", which the Azure CLI must be able to resolve"},
-						{Label: "Fix:", Value: "configure DNS or set LOCALSTACK_HOST"},
-					},
-				})
-				return output.NewSilentError(fmt.Errorf("dns resolution required for 'lstk az'"))
+			if _, err := azPreflight(cmd.Context(), cfg, sink); err != nil {
+				return err
 			}
 
 			azEnv := azureconfig.Env(azureConfigDir)
@@ -124,4 +73,121 @@ Examples:
 			return azurecli.Exec(cmd.Context(), azEnv, os.Stdin, stdout, stderr, args...)
 		},
 	}
+
+	cmd.AddCommand(newAzStartInterceptionCmd(cfg))
+	cmd.AddCommand(newAzStopInterceptionCmd(cfg))
+	return cmd
+}
+
+func newAzStartInterceptionCmd(cfg *env.Env) *cobra.Command {
+	return &cobra.Command{
+		Use:     "start-interception",
+		Short:   "Redirect global 'az' to the LocalStack Azure emulator",
+		Long:    "Register and activate a custom 'LocalStack' cloud in your global Azure CLI configuration (~/.azure) so that plain 'az' commands in any terminal target the LocalStack Azure emulator. This lets existing 'az' scripts run unmodified against LocalStack. It changes global state affecting every 'az' invocation until you run 'lstk az stop-interception'; this is independent of the isolated 'lstk az' setup.",
+		Args:    cobra.NoArgs,
+		PreRunE: initConfig(nil),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			preflight := func(ctx context.Context, sink output.Sink) (string, error) {
+				return azPreflight(ctx, cfg, sink)
+			}
+
+			// Run preflight under the same sink as the operation so its errors render
+			// in the TUI when interactive, instead of leaking plain output to stdout.
+			if isInteractiveMode(cfg) {
+				return ui.RunStartInterception(cmd.Context(), preflight)
+			}
+
+			sink := output.NewPlainSink(os.Stdout)
+			endpointURL, err := preflight(cmd.Context(), sink)
+			if err != nil {
+				return err
+			}
+			return azureconfig.StartInterception(cmd.Context(), sink, endpointURL)
+		},
+	}
+}
+
+func newAzStopInterceptionCmd(cfg *env.Env) *cobra.Command {
+	var cloud string
+	c := &cobra.Command{
+		Use:     "stop-interception",
+		Short:   "Switch global 'az' back to real Azure",
+		Long:    "Switch your global Azure CLI cloud away from the LocalStack emulator back to real Azure (AzureCloud by default; use --cloud to choose another registered cloud) and re-enable instance discovery. To avoid clobbering an unrelated selection, it only changes the active cloud when 'LocalStack' is currently active; otherwise it reports the current cloud and does nothing.",
+		Args:    cobra.NoArgs,
+		PreRunE: initConfig(nil),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if isInteractiveMode(cfg) {
+				return ui.RunStopInterception(cmd.Context(), cloud)
+			}
+			return azureconfig.StopInterception(cmd.Context(), output.NewPlainSink(os.Stdout), cloud)
+		},
+	}
+	c.Flags().StringVar(&cloud, "cloud", azureconfig.PublicCloudName, "Azure cloud to switch back to")
+	return c
+}
+
+// azPreflight runs the checks shared by 'lstk az' passthrough and 'start-interception':
+// the Azure CLI is installed, the Docker runtime is healthy, the Azure emulator is
+// running, and *.localhost.localstack.cloud resolves. On failure it emits the matching
+// ErrorEvent and returns a silent error. On success it returns the resolved LocalStack
+// Azure endpoint URL.
+func azPreflight(ctx context.Context, cfg *env.Env, sink output.Sink) (string, error) {
+	if err := azurecli.CheckInstalled(); err != nil {
+		sink.Emit(output.ErrorEvent{
+			Title:   "az CLI not found in PATH",
+			Actions: []output.ErrorAction{{Label: "Install Azure CLI:", Value: azurecli.InstallURL}},
+		})
+		return "", output.NewSilentError(err)
+	}
+
+	appCfg, err := config.Get()
+	if err != nil {
+		return "", fmt.Errorf("failed to get config: %w", err)
+	}
+	azureContainer := config.ContainerConfig{Type: config.EmulatorAzure, Port: config.DefaultPort}
+	for _, c := range appCfg.Containers {
+		if c.Type == config.EmulatorAzure {
+			azureContainer = c
+			break
+		}
+	}
+
+	rt, err := runtime.NewDockerRuntime(cfg.DockerHost)
+	if err != nil {
+		return "", err
+	}
+	if err := rt.IsHealthy(ctx); err != nil {
+		rt.EmitUnhealthyError(sink, err)
+		return "", output.NewSilentError(fmt.Errorf("runtime not healthy: %w", err))
+	}
+
+	runningName, err := container.ResolveRunningContainerName(ctx, rt, azureContainer)
+	if err != nil {
+		return "", fmt.Errorf("checking emulator status: %w", err)
+	}
+	if runningName == "" {
+		sink.Emit(output.ErrorEvent{
+			Title: fmt.Sprintf("%s is not running", azureContainer.DisplayName()),
+			Actions: []output.ErrorAction{
+				{Label: "Start LocalStack:", Value: "lstk"},
+				{Label: "See help:", Value: "lstk -h"},
+			},
+		})
+		return "", output.NewSilentError(fmt.Errorf("%s is not running", azureContainer.Name()))
+	}
+
+	resolvedHost, dnsOK := endpoint.ResolveHost(ctx, azureContainer.Port, cfg.LocalStackHost)
+	if !dnsOK {
+		sink.Emit(output.ErrorEvent{
+			Title: "DNS resolution required for 'lstk az'",
+			Actions: []output.ErrorAction{
+				{Label: "Note:", Value: "Could not resolve *." + endpoint.Hostname + " to 127.0.0.1."},
+				{Label: "Why:", Value: "the Azure emulator serves endpoints under *." + endpoint.Hostname + ", which the Azure CLI must be able to resolve"},
+				{Label: "Fix:", Value: "configure DNS or set LOCALSTACK_HOST"},
+			},
+		})
+		return "", output.NewSilentError(fmt.Errorf("dns resolution required for 'lstk az'"))
+	}
+
+	return azureconfig.BuildEndpoint(resolvedHost), nil
 }

internal/azureconfig/azureconfig.go

@@ -109,6 +109,31 @@ func cloudExists(ctx context.Context, azEnv []string) (bool, error) {
 	return strings.TrimSpace(stdout) == CloudName, nil
 }
 
+// ListClouds returns the names of all clouds registered in the Azure CLI config
+// selected by azEnv (built-ins like AzureCloud plus any custom-registered clouds).
+func ListClouds(ctx context.Context, azEnv []string) ([]string, error) {
+	stdout, _, err := azurecli.Run(ctx, azEnv, "cloud", "list", "--query", "[].name", "-o", "tsv")
+	if err != nil {
+		return nil, err
+	}
+	var names []string
+	for _, line := range strings.Split(stdout, "\n") {
+		if name := strings.TrimSpace(line); name != "" {
+			names = append(names, name)
+		}
+	}
+	return names, nil
+}
+
+// ActiveCloud returns the name of the currently active Azure CLI cloud.
+func ActiveCloud(ctx context.Context, azEnv []string) (string, error) {
+	stdout, _, err := azurecli.Run(ctx, azEnv, "cloud", "show", "--query", "name", "-o", "tsv")
+	if err != nil {
+		return "", err
+	}
+	return strings.TrimSpace(stdout), nil
+}
+
 // RunSetup derives the LocalStack Azure endpoint from the configured containers
 // and runs Setup against the isolated Azure CLI config dir under lstkConfigDir.
 // It works with any sink, so it serves both the interactive (TUI) and
@@ -162,8 +187,31 @@ func Setup(ctx context.Context, sink output.Sink, endpointURL, azureConfigDir st
 	if err := os.MkdirAll(azureConfigDir, 0700); err != nil {
 		return fmt.Errorf("could not create %s: %w", azureConfigDir, err)
 	}
-	azEnv := Env(azureConfigDir)
 
+	if err := registerLocalStackCloud(ctx, sink, Env(azureConfigDir), endpointURL, true); err != nil {
+		return err
+	}
+
+	if err := os.WriteFile(filepath.Join(azureConfigDir, setupMarkerFile), []byte("ok\n"), 0600); err != nil {
+		return fmt.Errorf("writing setup marker: %w", err)
+	}
+
+	sink.Emit(output.MessageEvent{
+		Severity: output.SeveritySuccess,
+		Text:     "Azure CLI integration ready. Run 'lstk az <command>' to talk to LocalStack.",
+	})
+	return nil
+}
+
+// registerLocalStackCloud registers (or updates) the LocalStack custom cloud in the
+// Azure CLI config selected by azEnv, activates it, disables instance discovery, and
+// logs in with the dummy service principal. A nil azEnv targets the user's global
+// ~/.azure; a non-nil azEnv (AZURE_CONFIG_DIR=...) targets an isolated dir.
+//
+// setLstkPrefs additionally disables telemetry and the survey link. That is fine for
+// the isolated dir but must not be forced on the user's global config, so interception
+// passes false.
+func registerLocalStackCloud(ctx context.Context, sink output.Sink, azEnv []string, endpointURL string, setLstkPrefs bool) error {
 	cloudConfigJSON, err := BuildCloudConfig(endpointURL)
 	if err != nil {
 		return fmt.Errorf("building cloud config: %w", err)
@@ -189,9 +237,12 @@ func Setup(ctx context.Context, sink output.Sink, endpointURL, azureConfigDir st
 
 	// instance_discovery=false: `az` would otherwise try to validate the authority
 	// against the public AAD discovery endpoint, which the emulator can't serve.
-	if _, _, err := azurecli.Run(ctx, azEnv, "config", "set",
-		"core.instance_discovery=false", "core.collect_telemetry=false", "output.show_survey_link=no",
-		"--only-show-errors"); err != nil {
+	configArgs := []string{"config", "set", "core.instance_discovery=false"}
+	if setLstkPrefs {
+		configArgs = append(configArgs, "core.collect_telemetry=false", "output.show_survey_link=no")
+	}
+	configArgs = append(configArgs, "--only-show-errors")
+	if _, _, err := azurecli.Run(ctx, azEnv, configArgs...); err != nil {
 		return fmt.Errorf("could not configure Azure CLI: %w", err)
 	}
 
@@ -204,14 +255,5 @@ func Setup(ctx context.Context, sink output.Sink, endpointURL, azureConfigDir st
 	); err != nil {
 		return fmt.Errorf("could not log in to the LocalStack Azure emulator: %w", err)
 	}
-
-	if err := os.WriteFile(filepath.Join(azureConfigDir, setupMarkerFile), []byte("ok\n"), 0600); err != nil {
-		return fmt.Errorf("writing setup marker: %w", err)
-	}
-
-	sink.Emit(output.MessageEvent{
-		Severity: output.SeveritySuccess,
-		Text:     "Azure CLI integration ready. Run 'lstk az <command>' to talk to LocalStack.",
-	})
 	return nil
 }