feat: add --dry-run flag to prepare and restore commands

README.md

@@ -113,6 +113,38 @@ export CONCIERGE_JUJU_CHANNEL=3.6/beta
 sudo concierge prepare -p dev
 ```
 
+### Dry Run Mode
+
+Both `prepare` and `restore` commands support a `--dry-run` flag that shows what
+operations would be performed without actually making any changes to the system.
+
+```bash
+# Preview prepare operations
+sudo concierge prepare -p dev --dry-run
+
+# Preview restore operations
+sudo concierge restore --dry-run
+```
+
+In dry-run mode:
+- Commands are printed to stdout in a format that can be copied and pasted into a shell
+- Log level defaults to error (use `--trace` or `--verbose` to see more details)
+- No packages are installed or removed
+- No files are created or modified
+- No Juju controllers are bootstrapped or destroyed
+- System state is read for accurate conditional logic (for example, checking if snaps are
+  already installed, reading configuration files)
+
+This is useful for verifying what `concierge` will do before running it, or for
+understanding what a particular preset or configuration file includes. Note that
+Concierge will still inspect the system (for example, to see what snaps are already
+installed), so dry-run mode runs read-only commands but never executes operations that
+modify system state.
+
+**Note:** Dry-run mode reads actual system state to provide accurate output. If your
+configuration references files that don't exist (e.g., Google Cloud credentials), the
+dry-run will fail with the same error that would occur during actual execution.
+
 ## Configuration
 
 ### Presets

cmd/main.go

@@ -28,20 +28,20 @@ func Execute() {
 func parseLoggingFlags(flags *pflag.FlagSet) {
 	verbose, _ := flags.GetBool("verbose")
 	trace, _ := flags.GetBool("trace")
+	dryRun, _ := flags.GetBool("dry-run")
 
-	logLevel := new(slog.LevelVar)
-
-	// Set the default log level to "DEBUG" if verbose is specified.
+	// Determine log level: --verbose/--trace take precedence, then --dry-run defaults to error
 	level := slog.LevelInfo
 	if verbose || trace {
 		level = slog.LevelDebug
+	} else if dryRun {
+		level = slog.LevelError
 	}
 
 	// Setup the TextHandler and ensure our configured logger is the default.
 	h := slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: level})
 	logger := slog.New(h)
 	slog.SetDefault(logger)
-	logLevel.Set(level)
 }
 
 func checkUser() error {

cmd/prepare.go

@@ -85,5 +85,7 @@ More information at https://github.com/canonical/concierge.
 		"comma-separated list of extra debs to install. E.g. 'make,python3-tox'",
 	)
 
+	flags.Bool("dry-run", false, "show what would be done without making changes")
+
 	return cmd
 }

cmd/restore.go

@@ -10,7 +10,7 @@ import (
 
 // restoreCmd constructs the `restore` subcommand
 func restoreCmd() *cobra.Command {
-	return &cobra.Command{
+	cmd := &cobra.Command{
 		Use:   "restore",
 		Short: "Run the reverse of `concierge prepare`.",
 		Long: `Run the reverse of 'concierge prepare'.
@@ -42,4 +42,9 @@ files or configuration that would normally be created during 'prepare' will be r
 			return mgr.Restore()
 		},
 	}
+
+	flags := cmd.Flags()
+	flags.Bool("dry-run", false, "show what would be done without making changes")
+
+	return cmd
 }

internal/concierge/manager.go

@@ -12,14 +12,19 @@ import (
 
 // NewManager constructs a new instance of the concierge manager.
 func NewManager(config *config.Config) (*Manager, error) {
-	system, err := system.NewSystem(config.Trace)
+	sys, err := system.NewSystem(config.Trace)
 	if err != nil {
 		return nil, fmt.Errorf("failed to initialise system: %w", err)
 	}
 
+	var worker system.Worker = sys
+	if config.DryRun {
+		worker = system.NewDryRunWorker(sys)
+	}
+
 	return &Manager{
 		config: config,
-		system: system,
+		system: worker,
 	}, nil
 }
 
@@ -65,9 +70,16 @@ func (m *Manager) execute(action string) error {
 			return fmt.Errorf("failed to record config file: %w", err)
 		}
 	case RestoreAction:
+		// Try to load the cached runtime config for accurate restore information.
+		// In dry-run mode, if no prepare has been run, fall back to current config.
 		err := m.loadRuntimeConfig()
 		if err != nil {
-			return fmt.Errorf("failed to load previous runtime configuration: %w", err)
+			if m.config.DryRun {
+				// In dry-run mode, use current config if no cached config exists
+				slog.Debug("No cached runtime config found, using current config for dry-run")
+			} else {
+				return fmt.Errorf("failed to load previous runtime configuration: %w", err)
+			}
 		}
 	default:
 		return fmt.Errorf("unknown handler action: %s", action)
@@ -80,7 +92,11 @@ func (m *Manager) execute(action string) error {
 
 // recordRuntimeConfig dumps the current manager config into a file in the user's home
 // directory, such that it can be read later and used to restore the machine.
+// In dry-run mode, this is a no-op.
 func (m *Manager) recordRuntimeConfig(status config.Status) error {
+	if m.config.DryRun {
+		return nil
+	}
 	m.config.Status = status
 	configYaml, err := yaml.Marshal(m.config)
 	if err != nil {

internal/config/config.go

@@ -49,9 +49,12 @@ func NewConfig(cmd *cobra.Command, flags *pflag.FlagSet) (*Config, error) {
 		}
 	}
 
+	dryRun, _ := flags.GetBool("dry-run")
+
 	conf.Overrides = getOverrides(flags)
 	conf.Verbose = verbose
 	conf.Trace = trace
+	conf.DryRun = dryRun
 
 	return conf, nil
 }

internal/config/config_format.go

@@ -11,6 +11,7 @@ type Config struct {
 	Status    Status          `mapstructure:"status"`
 	Verbose   bool            `mapstructure:"verbose"`
 	Trace     bool            `mapstructure:"trace"`
+	DryRun    bool            `mapstructure:"dry-run"`
 }
 
 // Status represents the status of concierge on a given machine.

internal/packages/dryrun_test.go

@@ -0,0 +1,201 @@
+package packages
+
+import (
+	"fmt"
+	"os"
+	"os/user"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/canonical/concierge/internal/system"
+)
+
+// testDryRunWorker is a test implementation that tracks commands
+// for verification without actually executing them
+type testDryRunWorker struct {
+	mu           sync.Mutex
+	executedCmds []string
+	mockSnapInfo map[string]*system.SnapInfo
+}
+
+func newTestDryRunWorker() *testDryRunWorker {
+	return &testDryRunWorker{
+		executedCmds: []string{},
+		mockSnapInfo: map[string]*system.SnapInfo{},
+	}
+}
+
+func (t *testDryRunWorker) User() *user.User {
+	return &user.User{Username: "test", Uid: "1000", Gid: "1000", HomeDir: "/tmp"}
+}
+
+func (t *testDryRunWorker) Run(c *system.Command) ([]byte, error) {
+	// This mock returns success without actually executing the command.
+	// We track the command strings for potential test assertions.
+	t.mu.Lock()
+	t.executedCmds = append(t.executedCmds, c.CommandString())
+	t.mu.Unlock()
+	return []byte{}, nil
+}
+
+func (t *testDryRunWorker) RunMany(commands ...*system.Command) error {
+	for _, c := range commands {
+		t.Run(c)
+	}
+	return nil
+}
+
+func (t *testDryRunWorker) RunExclusive(c *system.Command) ([]byte, error) {
+	return t.Run(c)
+}
+
+func (t *testDryRunWorker) RunWithRetries(c *system.Command, maxDuration time.Duration) ([]byte, error) {
+	return t.Run(c)
+}
+
+func (t *testDryRunWorker) WriteHomeDirFile(filepath string, contents []byte) error {
+	return nil
+}
+
+func (t *testDryRunWorker) ReadHomeDirFile(filepath string) ([]byte, error) {
+	return nil, fmt.Errorf("file not found")
+}
+
+func (t *testDryRunWorker) ReadFile(filePath string) ([]byte, error) {
+	return nil, fmt.Errorf("file not found")
+}
+
+func (t *testDryRunWorker) SnapInfo(snap string, channel string) (*system.SnapInfo, error) {
+	if info, ok := t.mockSnapInfo[snap]; ok {
+		return info, nil
+	}
+	return &system.SnapInfo{Installed: false, Classic: false}, nil
+}
+
+func (t *testDryRunWorker) SnapChannels(snap string) ([]string, error) {
+	return []string{"stable", "edge"}, nil
+}
+
+func (t *testDryRunWorker) RemovePath(path string) error {
+	return nil
+}
+
+func (t *testDryRunWorker) MkdirAll(path string, perm os.FileMode) error {
+	return nil
+}
+
+func (t *testDryRunWorker) ChownAll(path string, user *user.User) error {
+	return nil
+}
+
+func (t *testDryRunWorker) MockSnapInfo(name string, installed, classic bool) {
+	t.mockSnapInfo[name] = &system.SnapInfo{
+		Installed: installed,
+		Classic:   classic,
+	}
+}
+
+// Verify testDryRunWorker implements system.Worker
+var _ system.Worker = (*testDryRunWorker)(nil)
+
+func TestSnapHandlerExecutesCorrectCommands(t *testing.T) {
+	drw := newTestDryRunWorker()
+	drw.MockSnapInfo("existing-snap", true, false)
+
+	snaps := []*system.Snap{
+		system.NewSnap("new-snap", "stable", []string{}),
+		system.NewSnap("existing-snap", "stable", []string{}),
+	}
+
+	handler := NewSnapHandler(drw, snaps)
+	err := handler.Prepare()
+	if err != nil {
+		t.Fatalf("Prepare should not fail: %v", err)
+	}
+
+	// Verify the correct commands were issued
+	foundInstall := false
+	foundRefresh := false
+	for _, cmd := range drw.executedCmds {
+		if strings.Contains(cmd, "snap install new-snap") {
+			foundInstall = true
+		}
+		if strings.Contains(cmd, "snap refresh existing-snap") {
+			foundRefresh = true
+		}
+	}
+
+	if !foundInstall {
+		t.Errorf("expected 'snap install new-snap' command, got: %v", drw.executedCmds)
+	}
+	if !foundRefresh {
+		t.Errorf("expected 'snap refresh existing-snap' command, got: %v", drw.executedCmds)
+	}
+}
+
+func TestSnapHandlerRestoreExecutesCorrectCommands(t *testing.T) {
+	drw := newTestDryRunWorker()
+
+	snaps := []*system.Snap{
+		system.NewSnap("snap-to-remove", "stable", []string{}),
+	}
+
+	handler := NewSnapHandler(drw, snaps)
+	err := handler.Restore()
+	if err != nil {
+		t.Fatalf("Restore should not fail: %v", err)
+	}
+
+	foundRemove := false
+	for _, cmd := range drw.executedCmds {
+		if strings.Contains(cmd, "snap remove snap-to-remove") {
+			foundRemove = true
+		}
+	}
+
+	if !foundRemove {
+		t.Errorf("expected 'snap remove snap-to-remove' command, got: %v", drw.executedCmds)
+	}
+}
+
+func TestDebHandlerExecutesCorrectCommands(t *testing.T) {
+	drw := newTestDryRunWorker()
+
+	debs := []*Deb{
+		{Name: "make"},
+		{Name: "python3"},
+	}
+
+	handler := NewDebHandler(drw, debs)
+	err := handler.Prepare()
+	if err != nil {
+		t.Fatalf("Prepare should not fail: %v", err)
+	}
+
+	foundUpdate := false
+	foundMake := false
+	foundPython := false
+	for _, cmd := range drw.executedCmds {
+		if strings.Contains(cmd, "apt-get update") {
+			foundUpdate = true
+		}
+		if strings.Contains(cmd, "apt-get install") && strings.Contains(cmd, "make") {
+			foundMake = true
+		}
+		if strings.Contains(cmd, "apt-get install") && strings.Contains(cmd, "python3") {
+			foundPython = true
+		}
+	}
+
+	if !foundUpdate {
+		t.Errorf("expected 'apt-get update' command, got: %v", drw.executedCmds)
+	}
+	if !foundMake {
+		t.Errorf("expected 'apt-get install make' command, got: %v", drw.executedCmds)
+	}
+	if !foundPython {
+		t.Errorf("expected 'apt-get install python3' command, got: %v", drw.executedCmds)
+	}
+}