feat(component): add refresh-upstream-commit for lock-file-free mode

Register the component commands that maintain resolved state according to
the selected mode. The default mode keeps history, query, and update; the
lock-file-free mode instead gets refresh-upstream-commit, which resolves
each selected upstream component at the distro snapshot and records the
result as generated component TOML, plus hidden no-op stand-ins for the
lock-file commands so existing invocations report that they do nothing.

Because a stale generated pin can make strict configuration loading fail,
the refresh command is annotated to load configuration permissively, and
commands can now be excluded from generated Markdown docs so the no-op
stand-ins stay out of the reference documentation.

Component commands take construction options so that lock-file-only flags,
such as '--skip-lock-validation', are simply not registered in
lock-file-free mode instead of being accepted and ignored. Both modes are
exercised by unit tests, including a lock-file-free test environment.

Refs: microsoft#323

Author: Copilot

internal/app/azldev/app.go

@@ -50,6 +50,7 @@ type App struct {
 	reportFormat            ReportFormat
 	disableDefaultConfig    bool
 	permissiveConfigParsing bool
+	commandPermissiveConfig bool
 	configFiles             []string
 	colorMode               ColorMode
 	withoutLockfile         bool
@@ -137,7 +138,7 @@ lives), or use -C to point to one.`,
 			env.SetAcceptAllPrompts(app.acceptAllPrompts)
 			env.SetColorMode(app.colorMode)
 			env.SetNetworkRetries(app.networkRetries)
-			env.SetPermissiveConfigParsing(app.permissiveConfigParsing)
+			env.SetPermissiveConfigParsing(app.permissiveConfigEnabled())
 
 			return nil
 		},
@@ -262,6 +263,7 @@ func (a *App) Execute(args []string) int {
 	// the "right thing" to happen.
 	//
 	a.PreParseGlobalFlags(args)
+	a.commandPermissiveConfig = a.commandRequestsPermissiveConfig(args)
 
 	envOptions := a.initializeEnvOptions()
 
@@ -365,6 +367,25 @@ func (a *App) Execute(args []string) int {
 	return a.dispatchToCommand(env, args)
 }
 
+// commandRequestsPermissiveConfig reports whether the command selected by args asked
+// for permissive configuration loading via [CommandAnnotationPermissiveConfig].
+func (a *App) commandRequestsPermissiveConfig(args []string) bool {
+	cmd, _, err := a.cmd.Find(args)
+	if err != nil {
+		return false
+	}
+
+	_, permissive := cmd.Annotations[CommandAnnotationPermissiveConfig]
+
+	return permissive
+}
+
+// permissiveConfigEnabled reports whether configuration should be loaded permissively,
+// either because the user asked for it or because the selected command requires it.
+func (a *App) permissiveConfigEnabled() bool {
+	return a.permissiveConfigParsing || a.commandPermissiveConfig
+}
+
 func (*App) setCmdFactory(envOptions *EnvOptions) error {
 	cmdFactory, err := DefaultCmdFactory(envOptions.DryRunnable, envOptions.EventListener)
 	if err != nil {
@@ -603,7 +624,7 @@ func (a *App) findAndLoadConfig(tempDirPath string, extraConfigFiles []string) (
 		a.disableDefaultConfig,
 		tempDirPath,
 		extraConfigFiles,
-		a.permissiveConfigParsing,
+		a.permissiveConfigEnabled(),
 		a.withoutLockfile,
 	)
 	if err != nil {

internal/app/azldev/cmds/component/build.go

@@ -78,11 +78,11 @@ type ComponentBuildResults struct {
 	RPMs []RPMResult `json:"rpms" table:"-"`
 }
 
-func buildOnAppInit(_ *azldev.App, parent *cobra.Command) {
-	parent.AddCommand(NewBuildCmd())
+func buildOnAppInit(app *azldev.App, parent *cobra.Command) {
+	parent.AddCommand(NewBuildCmd(cmdOptionsForApp(app)...))
 }
 
-func NewBuildCmd() *cobra.Command {
+func NewBuildCmd(opts ...CmdOption) *cobra.Command {
 	// Fill out options defaults.
 	options := &ComponentBuildOptions{
 		BuildEnvPolicy: BuildEnvPreserveOnFailure,
@@ -127,7 +127,7 @@ builds can consume.`,
 		ValidArgsFunction: components.GenerateComponentNameCompletions,
 	}
 
-	components.AddComponentFilterOptionsToCommand(cmd, &options.ComponentFilter)
+	addComponentFilterOptions(cmd, &options.ComponentFilter, newCmdOptions(opts...))
 	cmd.Flags().BoolVarP(&options.ContinueOnError, "continue-on-error", "k", false,
 		"Continue building when some components fail")
 	cmd.Flags().BoolVar(&options.NoCheck, "no-check", false, "Skip package %check tests")

internal/app/azldev/cmds/component/changed.go

@@ -32,12 +32,12 @@ type ChangedComponentOptions struct {
 	IncludeUnchanged bool
 }
 
-func changedOnAppInit(_ *azldev.App, parentCmd *cobra.Command) {
-	parentCmd.AddCommand(NewChangedCmd())
+func changedOnAppInit(app *azldev.App, parentCmd *cobra.Command) {
+	parentCmd.AddCommand(NewChangedCmd(cmdOptionsForApp(app)...))
 }
 
 // NewChangedCmd constructs a [cobra.Command] for the "component changed" CLI subcommand.
-func NewChangedCmd() *cobra.Command {
+func NewChangedCmd(opts ...CmdOption) *cobra.Command {
 	options := &ChangedComponentOptions{}
 
 	cmd := &cobra.Command{
@@ -81,7 +81,8 @@ detected via lock file presence in the compared refs when using -a.`,
 		ValidArgsFunction: components.GenerateComponentNameCompletions,
 	}
 
-	components.AddComponentFilterOptionsToCommand(cmd, &options.ComponentFilter)
+	cmdOptions := newCmdOptions(opts...)
+	addComponentFilterOptions(cmd, &options.ComponentFilter, cmdOptions)
 
 	cmd.Flags().StringVar(&options.From, "from", "", "Git ref to compare from (required)")
 	cmd.Flags().StringVar(&options.To, "to", "HEAD", "Git ref to compare to")
@@ -92,7 +93,9 @@ detected via lock file presence in the compared refs when using -a.`,
 
 	// Hide inherited flag -- this command always skips lock validation since
 	// it inspects historical locks at arbitrary refs.
-	_ = cmd.Flags().MarkHidden("skip-lock-validation")
+	if !cmdOptions.withoutLockfile {
+		_ = cmd.Flags().MarkHidden("skip-lock-validation")
+	}
 
 	azldev.ExportAsReadOnlyMCPTool(cmd)
 

internal/app/azldev/cmds/component/cmdoptions.go

@@ -0,0 +1,62 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+package component
+
+import (
+	"github.com/microsoft/azure-linux-dev-tools/internal/app/azldev"
+	"github.com/microsoft/azure-linux-dev-tools/internal/app/azldev/core/components"
+	"github.com/spf13/cobra"
+)
+
+// cmdOptions holds the mode-sensitive choices made when a component command is
+// constructed. The zero value describes azldev's default (lock file) mode.
+type cmdOptions struct {
+	// withoutLockfile omits lock-file-specific flags, matching the command surface
+	// exposed by the global '--without-lockfile' flag.
+	withoutLockfile bool
+}
+
+// CmdOption customizes how a component command is constructed.
+type CmdOption func(*cmdOptions)
+
+// WithoutLockfileFlags omits the lock-file-specific flags from a component command.
+// Commands are registered with this option when the global '--without-lockfile'
+// flag selects lock-file-free mode, so the flags that only lock files can honor are
+// never offered.
+func WithoutLockfileFlags() CmdOption {
+	return func(options *cmdOptions) {
+		options.withoutLockfile = true
+	}
+}
+
+// newCmdOptions resolves the supplied command options.
+func newCmdOptions(opts ...CmdOption) cmdOptions {
+	options := cmdOptions{}
+	for _, opt := range opts {
+		opt(&options)
+	}
+
+	return options
+}
+
+// addComponentFilterOptions registers the component selection flags, including the
+// lock-file flags that only apply in azldev's default mode.
+func addComponentFilterOptions(
+	cmd *cobra.Command, filter *components.ComponentFilter, options cmdOptions,
+) {
+	components.AddComponentFilterOptionsToCommand(cmd, filter)
+
+	if !options.withoutLockfile {
+		components.AddLockValidationFlagToCommand(cmd, filter)
+	}
+}
+
+// cmdOptionsForApp returns the command options matching the app's selected mode.
+func cmdOptionsForApp(app *azldev.App) []CmdOption {
+	if app.WithoutLockfile() {
+		return []CmdOption{WithoutLockfileFlags()}
+	}
+
+	return nil
+}

internal/app/azldev/cmds/component/component.go

@@ -27,10 +27,20 @@ components defined in the project configuration.`,
 	buildOnAppInit(app, cmd)
 	changedOnAppInit(app, cmd)
 	diffSourcesOnAppInit(app, cmd)
-	historyOnAppInit(app, cmd)
 	listOnAppInit(app, cmd)
 	prepareOnAppInit(app, cmd)
-	queryOnAppInit(app, cmd)
 	renderOnAppInit(app, cmd)
-	updateOnAppInit(app, cmd)
+
+	// The commands that maintain resolved component state differ by mode: the
+	// default mode maintains lock files, while lock-file-free mode maintains
+	// generated upstream-commit config. Registering only the commands that
+	// belong to the active mode keeps help, docs, and MCP tools honest.
+	if app.WithoutLockfile() {
+		legacyOnAppInit(app, cmd)
+		refreshUpstreamCommitOnAppInit(app, cmd)
+	} else {
+		historyOnAppInit(app, cmd)
+		queryOnAppInit(app, cmd)
+		updateOnAppInit(app, cmd)
+	}
 }

internal/app/azldev/cmds/component/component_test.go

@@ -4,6 +4,7 @@
 package component_test
 
 import (
+	"slices"
 	"testing"
 
 	"github.com/microsoft/azure-linux-dev-tools/internal/app/azldev"
@@ -26,3 +27,52 @@ func TestOnAppInit(t *testing.T) {
 
 	assert.Contains(t, topLevelCommandNames, "component")
 }
+
+func TestOnAppInit_CommandsByMode(t *testing.T) {
+	testCases := []struct {
+		name            string
+		args            []string
+		refreshExpected bool
+	}{
+		{name: "default mode", args: nil, refreshExpected: false},
+		{name: "lock-file-free mode", args: []string{"--without-lockfile"}, refreshExpected: true},
+	}
+
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			ctrl := gomock.NewController(t)
+			app := azldev.NewApp(opctx_test.NewMockFileSystemFactory(ctrl), opctx_test.NewMockOSEnvFactory(ctrl))
+
+			app.PreParseGlobalFlags(testCase.args)
+			component.OnAppInit(app)
+
+			commandNames, err := app.CommandNames("component")
+			require.NoError(t, err)
+
+			assert.Equal(t, testCase.refreshExpected,
+				slices.Contains(commandNames, "refresh-upstream-commit"))
+
+			// The lock-file command names stay reachable in lock-file-free mode,
+			// where they are registered as hidden no-ops for compatibility.
+			for _, name := range []string{"history", "query", "update"} {
+				assert.Contains(t, commandNames, name)
+			}
+		})
+	}
+}
+
+func TestNewComponentCommands_LockValidationFlagByMode(t *testing.T) {
+	// The lock-file consistency flags only mean something when lock files are in
+	// play, so lock-file-free mode leaves them unregistered.
+	assert.NotNil(t, component.NewBuildCmd().Flags().Lookup("skip-lock-validation"))
+	assert.NotNil(t, component.NewRenderCmd().Flags().Lookup("skip-lock-validation"))
+	assert.NotNil(t, component.NewComponentListCommand().Flags().Lookup("skip-lock-validation"))
+	assert.NotNil(t, component.NewHistoryCmd().Flags().Lookup("skip-lock-validation"))
+	assert.NotNil(t, component.NewComponentQueryCommand().Flags().Lookup("skip-lock-validation"))
+	assert.NotNil(t, component.NewUpdateCmd().Flags().Lookup("skip-lock-validation"))
+
+	withoutLockfile := component.WithoutLockfileFlags()
+	assert.Nil(t, component.NewBuildCmd(withoutLockfile).Flags().Lookup("skip-lock-validation"))
+	assert.Nil(t, component.NewRenderCmd(withoutLockfile).Flags().Lookup("skip-lock-validation"))
+	assert.Nil(t, component.NewComponentListCommand(withoutLockfile).Flags().Lookup("skip-lock-validation"))
+}

internal/app/azldev/cmds/component/diffsources.go

@@ -28,12 +28,12 @@ type DiffSourcesOptions struct {
 	OutputFile string
 }
 
-func diffSourcesOnAppInit(_ *azldev.App, parentCmd *cobra.Command) {
-	parentCmd.AddCommand(NewDiffSourcesCmd())
+func diffSourcesOnAppInit(app *azldev.App, parentCmd *cobra.Command) {
+	parentCmd.AddCommand(NewDiffSourcesCmd(cmdOptionsForApp(app)...))
 }
 
 // NewDiffSourcesCmd constructs a [cobra.Command] for the "component diff-sources" CLI subcommand.
-func NewDiffSourcesCmd() *cobra.Command {
+func NewDiffSourcesCmd(opts ...CmdOption) *cobra.Command {
 	var options DiffSourcesOptions
 
 	cmd := &cobra.Command{
@@ -50,7 +50,7 @@ overlays to the copy and displays the resulting diff between the two trees.`,
 		ValidArgsFunction: components.GenerateComponentNameCompletions,
 	}
 
-	components.AddComponentFilterOptionsToCommand(cmd, &options.ComponentFilter)
+	addComponentFilterOptions(cmd, &options.ComponentFilter, newCmdOptions(opts...))
 
 	cmd.Flags().StringVar(&options.OutputFile, "output-file", "",
 		"write the diff output to a file instead of stdout")

internal/app/azldev/cmds/component/history.go

@@ -108,7 +108,7 @@ hand-picking entries to document.`,
 		ValidArgsFunction: components.GenerateComponentNameCompletions,
 	}
 
-	components.AddComponentFilterOptionsToCommand(cmd, &options.ComponentFilter)
+	addComponentFilterOptions(cmd, &options.ComponentFilter, cmdOptions{})
 
 	cmd.Flags().StringVar(&options.SharedTomlMode, "shared", sharedTomlModeShow,
 		"How to report rows for components that share a TOML file with others: "+

internal/app/azldev/cmds/component/legacy.go

@@ -0,0 +1,41 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+package component
+
+import (
+	"github.com/microsoft/azure-linux-dev-tools/internal/app/azldev"
+	"github.com/spf13/cobra"
+)
+
+const (
+	legacyUpdateMessage  = "azldev component update no longer does anything and should no longer be used."
+	legacyHistoryMessage = "azldev component history no longer does anything and should no longer be used."
+	legacyQueryMessage   = "azldev component query no longer does anything and should no longer be used."
+)
+
+func legacyOnAppInit(_ *azldev.App, parentCmd *cobra.Command) {
+	parentCmd.AddCommand(
+		newLegacyNoOpCmd("update", nil, legacyUpdateMessage),
+		newLegacyNoOpCmd("history", []string{"hist"}, legacyHistoryMessage),
+		newLegacyNoOpCmd("query", nil, legacyQueryMessage),
+	)
+}
+
+func newLegacyNoOpCmd(name string, aliases []string, message string) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:                name,
+		Aliases:            aliases,
+		Short:              message,
+		Hidden:             true,
+		DisableFlagParsing: true,
+		Args:               cobra.ArbitraryArgs,
+		Run: func(cmd *cobra.Command, _ []string) {
+			cmd.Println(message)
+		},
+	}
+
+	azldev.ExcludeFromMarkdownDocs(cmd)
+
+	return cmd
+}