feat(cli): add global --without-lockfile preview flag

Add a global, persistent '--without-lockfile' boolean flag that selects a
preview mode in which azldev tracks resolved upstream commits in generated
component configuration instead of per-component lock files. The flag
defaults to false, which keeps azldev's existing lock-file behavior
unchanged.

The registered command set and configuration loading both depend on the
mode, and both happen before cobra parses the command line, so the flag is
hand-parsed up front by App.PreParseGlobalFlags. Only exact
'--without-lockfile' and '--without-lockfile=<value>' tokens are
recognized, and scanning stops at the '--' terminator so positional text is
never mistaken for the flag. The CLI entry point pre-parses the process
arguments before registering commands; Execute pre-parses again so an App
executed directly behaves identically.

The mode is carried on Env via EnvOptions.WithoutLockfile, and the lock
store is not created when the mode is active, so every lock-file consumer
degrades to a no-op without needing mode-specific code.

The flag is part of the CLI surface, so the help, MCP tool-schema, and
usage-error snapshots pick up the new global option.

Refs: microsoft#323

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

Author: ddstreet

internal/app/azldev/app.go

@@ -11,6 +11,7 @@ import (
 	"os"
 	"os/signal"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"time"
 
@@ -51,6 +52,7 @@ type App struct {
 	permissiveConfigParsing bool
 	configFiles             []string
 	colorMode               ColorMode
+	withoutLockfile         bool
 
 	// Root command for the CLI.
 	cmd cobra.Command
@@ -184,6 +186,8 @@ func (app *App) registerGlobalFlags() {
 		"output colorization mode {always, auto, never}")
 	app.cmd.PersistentFlags().BoolVar(&app.permissiveConfigParsing, "permissive-config",
 		false, "do not fail on unknown fields in TOML config files")
+	app.cmd.PersistentFlags().BoolVar(&app.withoutLockfile, "without-lockfile", false,
+		"preview: track resolved upstream commits in generated config instead of lock files")
 }
 
 // addAdvancedCommandHint embeds a hint about the hidden "advanced" command group
@@ -257,7 +261,7 @@ func (a *App) Execute(args []string) int {
 	// We tried to do this with cobra first, but it was too difficult to get
 	// the "right thing" to happen.
 	//
-	a.handParseConfigFlags(args)
+	a.PreParseGlobalFlags(args)
 
 	envOptions := a.initializeEnvOptions()
 
@@ -397,6 +401,7 @@ func (a *App) initializeEnvOptions() *EnvOptions {
 	envOptions.Interfaces.FileSystemFactory = a.fsFactory
 	envOptions.Interfaces.OSEnvFactory = a.osEnvFactory
 	envOptions.DryRunnable = NewAppDryRunnable(a.dryRun)
+	envOptions.WithoutLockfile = a.withoutLockfile
 
 	return &envOptions
 }
@@ -458,6 +463,68 @@ func setEventListener(stdioLogger *slog.Logger, quiet, verbose bool, envOptions
 	return nil
 }
 
+// PreParseGlobalFlags hand-parses the global flags that must be known before commands
+// are registered and configuration is loaded. It is safe to call more than once with the
+// same arguments; each call fully recomputes the pre-parsed state.
+//
+// Command registration is mode-sensitive, so the CLI entry point calls this before it
+// registers commands; [App.Execute] calls it again so that an App executed directly
+// (e.g. from a test) behaves identically.
+func (a *App) PreParseGlobalFlags(args []string) {
+	// Reset accumulating state so repeated calls are idempotent.
+	a.configFiles = nil
+
+	a.withoutLockfile = parseWithoutLockfileFlag(args)
+	a.handParseConfigFlags(args)
+}
+
+// WithoutLockfile reports whether the preview lock-file-free mode was requested via the
+// global '--without-lockfile' flag. Valid only after [App.PreParseGlobalFlags] has run.
+func (a *App) WithoutLockfile() bool {
+	return a.withoutLockfile
+}
+
+// withoutLockfileFlagName is the global flag that selects lock-file-free mode.
+const withoutLockfileFlagName = "--without-lockfile"
+
+// parseWithoutLockfileFlag hand-parses the global '--without-lockfile' boolean flag.
+//
+// Only exact '--without-lockfile' and '--without-lockfile=<value>' tokens are
+// recognized, and scanning stops at the '--' terminator so that positional text
+// (for example a mock command line) is never mistaken for the flag. An invalid or
+// missing value is treated the same way cobra treats it: '--without-lockfile' alone
+// enables the mode, and an unparseable '=<value>' leaves the mode disabled so the
+// final cobra parse reports the error.
+func parseWithoutLockfileFlag(args []string) bool {
+	withoutLockfile := false
+
+	for _, arg := range args {
+		if arg == "--" {
+			break
+		}
+
+		if arg == withoutLockfileFlagName {
+			withoutLockfile = true
+
+			continue
+		}
+
+		value, found := strings.CutPrefix(arg, withoutLockfileFlagName+"=")
+		if !found {
+			continue
+		}
+
+		parsed, err := strconv.ParseBool(value)
+		if err != nil {
+			return false
+		}
+
+		withoutLockfile = parsed
+	}
+
+	return withoutLockfile
+}
+
 // Hand-parses a few critical configuration flags from the command line -- just enough to
 // find the project and load configuration so we can properly use cobra facilities to
 // parse the full command line.

internal/app/azldev/app_test.go

@@ -193,3 +193,100 @@ func TestApp_PermissiveConfigOption_DefaultFalse(t *testing.T) {
 	assert.Zero(t, result)
 	assert.True(t, ran)
 }
+
+func TestApp_WithoutLockfileOption(t *testing.T) {
+	testCases := []struct {
+		name     string
+		args     []string
+		expected bool
+	}{
+		{name: "absent", args: []string{"test-cmd"}, expected: false},
+		{name: "bare", args: []string{"--without-lockfile", "test-cmd"}, expected: true},
+		{name: "explicit true", args: []string{"--without-lockfile=true", "test-cmd"}, expected: true},
+		{name: "explicit false", args: []string{"--without-lockfile=false", "test-cmd"}, expected: false},
+		{name: "after command", args: []string{"test-cmd", "--without-lockfile"}, expected: true},
+		{name: "positional lookalike", args: []string{"test-cmd", "--", "--without-lockfile"}, expected: false},
+		{name: "prefix lookalike", args: []string{"test-cmd", "--without-lockfiles"}, expected: false},
+	}
+
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			app := createTestApp(t)
+
+			app.PreParseGlobalFlags(testCase.args)
+
+			assert.Equal(t, testCase.expected, app.WithoutLockfile())
+		})
+	}
+}
+
+func TestApp_WithoutLockfileOption_ReachesEnv(t *testing.T) {
+	testCases := []struct {
+		name     string
+		args     []string
+		expected bool
+	}{
+		{name: "default", args: []string{"test-cmd"}, expected: false},
+		{name: "enabled", args: []string{"--without-lockfile", "test-cmd"}, expected: true},
+		{name: "disabled", args: []string{"--without-lockfile=false", "test-cmd"}, expected: false},
+	}
+
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			app := createTestApp(t)
+
+			ran := false
+			cmd := &cobra.Command{
+				Use: "test-cmd",
+				RunE: func(cmd *cobra.Command, _ []string) error {
+					env, err := azldev.GetEnvFromCommand(cmd)
+					require.NoError(t, err)
+
+					assert.Equal(t, testCase.expected, env.WithoutLockfile())
+
+					ran = true
+
+					return nil
+				},
+			}
+
+			app.AddTopLevelCommand(cmd)
+
+			assert.Zero(t, app.Execute(testCase.args))
+			assert.True(t, ran)
+		})
+	}
+}
+
+// PreParseGlobalFlags is called both by the CLI entry point (before command
+// registration) and by Execute; repeated calls must not accumulate state.
+func TestApp_PreParseGlobalFlags_Idempotent(t *testing.T) {
+	app := createTestApp(t)
+	args := []string{"--without-lockfile", "--config-file", "extra.toml", "test-cmd"}
+
+	ran := false
+	cmd := &cobra.Command{
+		Use: "test-cmd",
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			env, err := azldev.GetEnvFromCommand(cmd)
+			require.NoError(t, err)
+
+			assert.True(t, env.WithoutLockfile())
+
+			ran = true
+
+			return nil
+		},
+	}
+
+	app.AddTopLevelCommand(cmd)
+	app.PreParseGlobalFlags(args)
+	app.PreParseGlobalFlags(args)
+
+	assert.True(t, app.WithoutLockfile())
+
+	// Execute pre-parses the same arguments a third time; a command that only
+	// accumulated config files would fail to load its (nonexistent) extra file.
+	assert.Zero(t, app.Execute(args))
+	assert.True(t, ran)
+}

internal/app/azldev/env.go

@@ -33,6 +33,12 @@ type EnvOptions struct {
 	// The loaded configuration for the project.
 	Config *projectconfig.ProjectConfig
 
+	// WithoutLockfile selects the preview lock-file-free mode, in which
+	// component state is tracked by generated upstream-commit config instead
+	// of per-component lock files. Set from the global '--without-lockfile'
+	// flag; false selects the default lock-file behavior.
+	WithoutLockfile bool
+
 	// Injected dependencies.
 	DryRunnable   opctx.DryRunnable
 	EventListener opctx.EventListener
@@ -73,6 +79,7 @@ type Env struct {
 	acceptAllPrompts        bool
 	networkRetries          int
 	permissiveConfigParsing bool
+	withoutLockfile         bool
 
 	// Injected dependencies.
 	cmdFactory    opctx.CmdFactory
@@ -96,7 +103,8 @@ type Env struct {
 	fixSuggestions *fixSuggestionState
 
 	// lockStore provides cached access to per-component lock files.
-	// Nil when no project directory is configured.
+	// Nil when no project directory is configured, or when lock-file-free
+	// mode is selected.
 	lockStore *lockfile.Store
 }
 
@@ -167,15 +175,17 @@ func NewEnv(ctx context.Context, options EnvOptions) *Env {
 		quiet:                   false,
 		promptsAllowed:          isatty.IsTerminal(os.Stdin.Fd()),
 		permissiveConfigParsing: false,
+		withoutLockfile:         options.WithoutLockfile,
 
 		// Start time.
 		constructionTime: time.Now(),
 
 		// No fix suggestions to start.
 		fixSuggestions: &fixSuggestionState{},
 
-		// Lock store: created when we have a project directory.
-		lockStore: newLockStore(options.ProjectDir, options.Config, options.Interfaces.FileSystemFactory),
+		// Lock store: created when we have a project directory, unless
+		// lock-file-free mode is selected.
+		lockStore: newLockStore(options, options.Interfaces.FileSystemFactory),
 	}
 }
 
@@ -242,6 +252,13 @@ func (env *Env) SetPermissiveConfigParsing(permissive bool) {
 	env.permissiveConfigParsing = permissive
 }
 
+// WithoutLockfile reports whether the preview lock-file-free mode is active.
+// In that mode azldev tracks resolved upstream commits in generated component
+// config instead of per-component lock files, and no lock store is available.
+func (env *Env) WithoutLockfile() bool {
+	return env.withoutLockfile
+}
+
 // SetEventListener registers the event listener to be used in this environment.
 func (env *Env) SetEventListener(eventListener opctx.EventListener) {
 	env.eventListener = eventListener
@@ -385,14 +402,16 @@ func (env *Env) LockReader() lockfile.LockReader {
 }
 
 // newLockStore creates a lock store from the project config's lock-dir.
-// Returns nil when the project directory, filesystem, or config is unavailable,
-// or when the config's lock-dir is empty.
+// Returns nil when lock-file-free mode is selected, or when the project
+// directory, filesystem, or config is unavailable, or when the config's
+// lock-dir is empty.
 func newLockStore(
-	projectDir string,
-	config *projectconfig.ProjectConfig,
+	options EnvOptions,
 	fsFactory opctx.FileSystemFactory,
 ) *lockfile.Store {
-	if projectDir == "" || fsFactory == nil || config == nil || config.Project.LockDir == "" {
+	config := options.Config
+	if options.WithoutLockfile || options.ProjectDir == "" || fsFactory == nil ||
+		config == nil || config.Project.LockDir == "" {
 		return nil
 	}
 

pkg/app/azldev_cli/azldev.go

@@ -26,21 +26,35 @@ import (
 // Main constructs the azldev CLI application, runs it with the process
 // arguments, and exits the process with the resulting status code.
 func Main() {
-	// Instantiate the main CLI app instance.
-	app := InstantiateApp()
+	args := os.Args[1:]
+
+	// Instantiate the main CLI app instance. The arguments are needed up front
+	// because command registration depends on the global flags they carry.
+	app := InstantiateAppForArgs(args)
 
 	// Execute! We'll get back an exit code that we will exit with.
-	ret := app.Execute(os.Args[1:])
+	ret := app.Execute(args)
 
 	os.Exit(ret)
 }
 
 // InstantiateApp constructs a new instance of the azldev CLI application with
-// all subcommands registered.
+// all subcommands registered for azldev's default (lock file) mode.
 func InstantiateApp() *azldev.App {
+	return InstantiateAppForArgs(nil)
+}
+
+// InstantiateAppForArgs constructs a new instance of the azldev CLI application
+// with the subcommands registered for the mode selected by args. Global flags
+// that select a mode (such as '--without-lockfile') are hand-parsed from args
+// before registration, because the registered command set differs by mode.
+func InstantiateAppForArgs(args []string) *azldev.App {
 	// Instantiate the main CLI application.
 	app := azldev.NewApp(azldev.DefaultFileSystemFactory(), azldev.DefaultOSEnvFactory())
 
+	// Resolve the global flags that command registration depends on.
+	app.PreParseGlobalFlags(args)
+
 	// Give top level command packages an opportunity to register their commands (or in some cases,
 	// request post-init callbacks).
 	advanced.OnAppInit(app)