feat: add --force flag to PrepareSourcesOptions and CLI registration (#467)

* feat: add --force flag to PrepareSourcesOptions and CLI registration

Add Force bool field to PrepareSourcesOptions struct and register the
--force CLI flag (default false) with description: "delete and recreate
the output directory if it already exists".

Also fix MCP server magemcp to resolve project root to absolute path,
enabling relative path arguments to work correctly.

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

* feedback

---------

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

Author: 3 people

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

@@ -11,6 +11,7 @@ import (
 	"github.com/gim-home/azldev-preview/internal/app/azldev/core/components"
 	"github.com/gim-home/azldev-preview/internal/app/azldev/core/sources"
 	"github.com/gim-home/azldev-preview/internal/providers/sourceproviders"
+	"github.com/gim-home/azldev-preview/internal/utils/fileutils"
 	"github.com/spf13/cobra"
 )
 
@@ -19,6 +20,7 @@ type PrepareSourcesOptions struct {
 
 	OutputDir    string
 	SkipOverlays bool
+	Force        bool
 }
 
 func prepareOnAppInit(_ *azldev.App, sourceCmd *cobra.Command) {
@@ -50,6 +52,7 @@ func NewPrepareSourcesCmd() *cobra.Command {
 	_ = cmd.MarkFlagDirname("output-dir")
 
 	cmd.Flags().BoolVar(&options.SkipOverlays, "skip-overlays", false, "skip applying overlays to prepared sources")
+	cmd.Flags().BoolVar(&options.Force, "force", false, "delete and recreate the output directory if it already exists")
 
 	return cmd
 }
@@ -87,6 +90,11 @@ func PrepareComponentSources(env *azldev.Env, options *PrepareSourcesOptions) er
 		return fmt.Errorf("failed to create source manager:\n%w", err)
 	}
 
+	// Pre-flight check: detect non-empty output directory before any work.
+	if err := CheckOutputDir(env, options); err != nil {
+		return err
+	}
+
 	preparer, err := sources.NewPreparer(sourceManager, env.FS(), env, env)
 	if err != nil {
 		return fmt.Errorf("failed to create source preparer:\n%w", err)
@@ -99,3 +107,39 @@ func PrepareComponentSources(env *azldev.Env, options *PrepareSourcesOptions) er
 
 	return nil
 }
+
+// CheckOutputDir verifies the output directory state before source preparation.
+// If the directory exists and is non-empty, it either removes it (when Force is set)
+// or returns an actionable error suggesting --force.
+func CheckOutputDir(env *azldev.Env, options *PrepareSourcesOptions) error {
+	dirExists, err := fileutils.DirExists(env.FS(), options.OutputDir)
+	if err != nil {
+		return fmt.Errorf("failed to check output directory %#q:\n%w", options.OutputDir, err)
+	}
+
+	if !dirExists {
+		return nil
+	}
+
+	empty, err := fileutils.IsDirEmpty(env.FS(), options.OutputDir)
+	if err != nil {
+		return fmt.Errorf("failed to check if output directory %#q is empty:\n%w", options.OutputDir, err)
+	}
+
+	if empty {
+		return nil
+	}
+
+	if options.Force {
+		if err := env.FS().RemoveAll(options.OutputDir); err != nil {
+			return fmt.Errorf("failed to clean output directory %#q:\n%w", options.OutputDir, err)
+		}
+
+		return nil
+	}
+
+	return fmt.Errorf(
+		"output directory %#q already exists and is not empty;\n"+
+			"use --force to delete and recreate it",
+		options.OutputDir)
+}

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

@@ -8,6 +8,8 @@ import (
 
 	"github.com/gim-home/azldev-preview/internal/app/azldev/cmds/component"
 	"github.com/gim-home/azldev-preview/internal/app/azldev/core/testutils"
+	"github.com/gim-home/azldev-preview/internal/utils/fileperms"
+	"github.com/gim-home/azldev-preview/internal/utils/fileutils"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -16,6 +18,11 @@ func TestNewPrepareSourcesCmd(t *testing.T) {
 	cmd := component.NewPrepareSourcesCmd()
 	require.NotNil(t, cmd)
 	assert.Equal(t, "prepare-sources", cmd.Use)
+
+	forceFlag := cmd.Flags().Lookup("force")
+	require.NotNil(t, forceFlag, "--force flag should be registered")
+	assert.Equal(t, "false", forceFlag.DefValue)
+	assert.Contains(t, forceFlag.Usage, "delete and recreate the output directory")
 }
 
 func TestPrepareSourcesCmd_NoMatch(t *testing.T) {
@@ -31,3 +38,106 @@ func TestPrepareSourcesCmd_NoMatch(t *testing.T) {
 	// We expect an error because we haven't set up any components.
 	require.Error(t, err)
 }
+
+func TestCheckOutputDir(t *testing.T) {
+	const (
+		outputDir = "/test/output"
+		staleFile = "/test/output/stale.txt"
+	)
+
+	tests := []struct {
+		name             string
+		force            bool
+		setupDir         bool
+		addFile          bool
+		expectError      bool
+		errorMsgContains []string
+	}{
+		{
+			name:        "default with nonexistent dir succeeds",
+			force:       false,
+			setupDir:    false,
+			addFile:     false,
+			expectError: false,
+		},
+		{
+			name:        "default with empty dir succeeds",
+			force:       false,
+			setupDir:    true,
+			addFile:     false,
+			expectError: false,
+		},
+		{
+			name:             "default with non-empty dir returns actionable error",
+			force:            false,
+			setupDir:         true,
+			addFile:          true,
+			expectError:      true,
+			errorMsgContains: []string{"--force", outputDir},
+		},
+		{
+			name:        "force with nonexistent dir succeeds",
+			force:       true,
+			setupDir:    false,
+			addFile:     false,
+			expectError: false,
+		},
+		{
+			name:        "force with empty dir succeeds",
+			force:       true,
+			setupDir:    true,
+			addFile:     false,
+			expectError: false,
+		},
+		{
+			name:        "force with non-empty dir removes dir",
+			force:       true,
+			setupDir:    true,
+			addFile:     true,
+			expectError: false,
+		},
+	}
+
+	for _, testCase := range tests {
+		t.Run(testCase.name, func(t *testing.T) {
+			testEnv := testutils.NewTestEnv(t)
+			testFS := testEnv.TestFS
+
+			if testCase.setupDir {
+				require.NoError(t, testFS.MkdirAll(outputDir, fileperms.PublicDir))
+			}
+
+			if testCase.addFile {
+				require.NoError(t, testFS.MkdirAll(outputDir, fileperms.PublicDir))
+
+				f, err := testFS.Create(staleFile)
+				require.NoError(t, err)
+				require.NoError(t, f.Close())
+			}
+
+			options := &component.PrepareSourcesOptions{
+				OutputDir: outputDir,
+				Force:     testCase.force,
+			}
+
+			err := component.CheckOutputDir(testEnv.Env, options)
+
+			if testCase.expectError {
+				require.Error(t, err)
+
+				for _, msg := range testCase.errorMsgContains {
+					assert.Contains(t, err.Error(), msg)
+				}
+			} else {
+				require.NoError(t, err)
+			}
+
+			// Verify force actually removed the directory.
+			if testCase.force && testCase.addFile {
+				exists, err := fileutils.Exists(testFS, outputDir)
+				require.NoError(t, err)
+				assert.False(t, exists, "output directory should be removed when --force is used")
+			}
+		})
+	}
+}

internal/utils/fileutils/dir.go

@@ -63,3 +63,9 @@ func ReadDir(fs opctx.FS, name string) (entries []os.FileInfo, err error) {
 	//nolint:wrapcheck // We are intentionally a pass-through.
 	return dir.Readdir(-1)
 }
+
+// IsDirEmpty checks if a directory exists and is empty.
+func IsDirEmpty(fs opctx.FS, path string) (bool, error) {
+	//nolint:wrapcheck // We are intentionally a pass-through.
+	return afero.IsEmpty(fs, path)
+}