feat: add two-way manifest sync between project and app settings

When the manifest-sync experiment is enabled, the CLI detects per-field
differences between the local manifest.json and the remote app settings,
lets the user resolve them interactively, and writes the merged result to
both sides. This replaces the binary "overwrite?" prompt when divergence
is detected during install/deploy.

Adds `slack manifest sync` command and `slack sync` alias.
Gated behind --experiment=manifest-sync.

Author: mwbrooks

cmd/manifest/manifest.go

@@ -79,6 +79,7 @@ func NewCommand(clients *shared.ClientFactory) *cobra.Command {
 
 	// Add child commands
 	cmd.AddCommand(NewInfoCommand(clients))
+	cmd.AddCommand(NewSyncCommand(clients))
 	cmd.AddCommand(NewValidateCommand(clients))
 
 	cmd.Flags().StringVar(

cmd/manifest/sync.go

@@ -0,0 +1,45 @@
+package manifest
+
+import (
+	"github.com/opentracing/opentracing-go"
+	"github.com/slackapi/slack-cli/internal/app"
+	"github.com/slackapi/slack-cli/internal/cmdutil"
+	"github.com/slackapi/slack-cli/internal/pkg/manifest"
+	"github.com/slackapi/slack-cli/internal/prompts"
+	"github.com/slackapi/slack-cli/internal/shared"
+	"github.com/slackapi/slack-cli/internal/style"
+	"github.com/spf13/cobra"
+)
+
+var manifestSyncFunc = manifest.Sync
+
+func NewSyncCommand(clients *shared.ClientFactory) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "sync",
+		Short: "Sync the app manifest between project and app settings",
+		Long:  "Compare the local project manifest with app settings, resolve differences, and sync both to the same state.",
+		Example: style.ExampleCommandsf([]style.ExampleCommand{
+			{Command: "manifest sync", Meaning: "Sync project manifest with app settings"},
+		}),
+		Args: cobra.NoArgs,
+		PreRunE: func(cmd *cobra.Command, args []string) error {
+			return cmdutil.IsValidProjectDirectory(clients)
+		},
+		RunE: func(cmd *cobra.Command, args []string) error {
+			ctx := cmd.Context()
+			span, ctx := opentracing.StartSpanFromContext(ctx, "cmd.manifest.sync")
+			defer span.Finish()
+
+			selection, err := appSelectPromptFunc(ctx, clients, prompts.ShowAllEnvironments, prompts.ShowInstalledAppsOnly)
+			if err != nil {
+				return err
+			}
+
+			clients.Config.ManifestEnv = app.SetManifestEnvTeamVars(clients.Config.ManifestEnv, selection.App.TeamDomain, selection.App.IsDev)
+
+			_, err = manifestSyncFunc(ctx, clients, selection.App, selection.Auth)
+			return err
+		},
+	}
+	return cmd
+}

cmd/root.go

@@ -80,6 +80,7 @@ var AliasMap = map[string]*AliasInfo{
 	"logout":    {CommandFactory: auth.NewLogoutCommand, CanonicalName: "auth logout", ParentName: "auth"},
 	"run":       {CommandFactory: platform.NewRunCommand, CanonicalName: "platform run", ParentName: "platform"},
 	"samples":   {CommandFactory: project.NewSamplesCommand, CanonicalName: "project samples", ParentName: "project"},
+	"sync":      {CommandFactory: manifest.NewSyncCommand, CanonicalName: "manifest sync", ParentName: "manifest"},
 	"uninstall": {CommandFactory: app.NewUninstallCommand, CanonicalName: "app uninstall", ParentName: "app"},
 }
 var processName = cmdutil.GetProcessName()

internal/experiment/experiment.go

@@ -33,6 +33,9 @@ const (
 	// Lipgloss experiment shows pretty styles.
 	Lipgloss Experiment = "lipgloss"
 
+	// ManifestSync experiment enables two-way manifest sync between local and remote.
+	ManifestSync Experiment = "manifest-sync"
+
 	// Placeholder experiment is a placeholder for testing and does nothing... or does it?
 	Placeholder Experiment = "placeholder"
 
@@ -47,6 +50,7 @@ const (
 // Please also add here 👇
 var AllExperiments = []Experiment{
 	Lipgloss,
+	ManifestSync,
 	Placeholder,
 	Sandboxes,
 	SetIcon,

internal/pkg/apps/install.go

@@ -25,7 +25,7 @@ import (
 	"github.com/slackapi/slack-cli/internal/config"
 	"github.com/slackapi/slack-cli/internal/experiment"
 	"github.com/slackapi/slack-cli/internal/icon"
-	"github.com/slackapi/slack-cli/internal/pkg/manifest"
+	manifestpkg "github.com/slackapi/slack-cli/internal/pkg/manifest"
 	"github.com/slackapi/slack-cli/internal/shared"
 	"github.com/slackapi/slack-cli/internal/shared/types"
 	"github.com/slackapi/slack-cli/internal/slackerror"
@@ -273,11 +273,11 @@ func printNonSuccessInstallState(ctx context.Context, clients *shared.ClientFact
 func validateManifestForInstall(ctx context.Context, clients *shared.ClientFactory, token string, app types.App, appManifest types.AppManifest) error {
 	validationResult, err := clients.API().ValidateAppManifest(ctx, token, appManifest, app.AppID)
 
-	if retryValidate := manifest.HandleConnectorNotInstalled(ctx, clients, token, err); retryValidate {
+	if retryValidate := manifestpkg.HandleConnectorNotInstalled(ctx, clients, token, err); retryValidate {
 		validationResult, err = clients.API().ValidateAppManifest(ctx, token, appManifest, app.AppID)
 	}
 
-	if err := manifest.HandleConnectorApprovalRequired(ctx, clients, token, err); err != nil {
+	if err := manifestpkg.HandleConnectorApprovalRequired(ctx, clients, token, err); err != nil {
 		return err
 	}
 
@@ -764,6 +764,15 @@ func shouldUpdateManifest(ctx context.Context, clients *shared.ClientFactory, ap
 	default:
 		notice = style.Yellow("The manifest on app settings has been changed since last update")
 	}
+
+	if clients.Config.WithExperimentOn(experiment.ManifestSync) {
+		_, err := manifestpkg.Sync(ctx, clients, app, auth)
+		if err != nil {
+			return false, err
+		}
+		return false, nil
+	}
+
 	clients.IO.PrintInfo(ctx, false, "\n%s", style.Sectionf(style.TextSection{
 		Emoji:     "books",
 		Text:      "App Manifest",

internal/pkg/manifest/diff.go

@@ -0,0 +1,100 @@
+package manifest
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"github.com/slackapi/slack-cli/internal/shared/types"
+)
+
+// DiffType describes how a field differs between local and remote.
+type DiffType int
+
+const (
+	DiffModified   DiffType = iota // Both sides have the field but with different values
+	DiffLocalOnly                  // Field exists only in local (added locally or deleted remotely)
+	DiffRemoteOnly                 // Field exists only in remote (added remotely or deleted locally)
+)
+
+// FieldDiff represents a single difference between local and remote manifests.
+type FieldDiff struct {
+	Path        string
+	Type        DiffType
+	LocalValue  any
+	RemoteValue any
+}
+
+// DiffResult holds all differences found between two manifests.
+type DiffResult struct {
+	Diffs []FieldDiff
+}
+
+// HasDifferences returns true if any differences were found.
+func (dr *DiffResult) HasDifferences() bool {
+	return len(dr.Diffs) > 0
+}
+
+// Diff performs a two-way comparison between local and remote manifests,
+// returning all fields that differ between them.
+func Diff(local, remote types.AppManifest) (*DiffResult, error) {
+	localFlat, err := Flatten(local)
+	if err != nil {
+		return nil, fmt.Errorf("failed to flatten local manifest: %w", err)
+	}
+	remoteFlat, err := Flatten(remote)
+	if err != nil {
+		return nil, fmt.Errorf("failed to flatten remote manifest: %w", err)
+	}
+	return diffFlat(localFlat, remoteFlat), nil
+}
+
+func diffFlat(local, remote map[string]any) *DiffResult {
+	result := &DiffResult{}
+	seen := make(map[string]bool)
+
+	for path, localVal := range local {
+		seen[path] = true
+		remoteVal, exists := remote[path]
+		if !exists {
+			result.Diffs = append(result.Diffs, FieldDiff{
+				Path:       path,
+				Type:       DiffLocalOnly,
+				LocalValue: localVal,
+			})
+			continue
+		}
+		if !valuesEqual(localVal, remoteVal) {
+			result.Diffs = append(result.Diffs, FieldDiff{
+				Path:        path,
+				Type:        DiffModified,
+				LocalValue:  localVal,
+				RemoteValue: remoteVal,
+			})
+		}
+	}
+
+	for path, remoteVal := range remote {
+		if seen[path] {
+			continue
+		}
+		result.Diffs = append(result.Diffs, FieldDiff{
+			Path:        path,
+			Type:        DiffRemoteOnly,
+			RemoteValue: remoteVal,
+		})
+	}
+
+	return result
+}
+
+func valuesEqual(a, b any) bool {
+	aJSON, err := json.Marshal(a)
+	if err != nil {
+		return false
+	}
+	bJSON, err := json.Marshal(b)
+	if err != nil {
+		return false
+	}
+	return string(aJSON) == string(bJSON)
+}

internal/pkg/manifest/diff_test.go

@@ -0,0 +1,143 @@
+package manifest
+
+import (
+	"testing"
+
+	"github.com/slackapi/slack-cli/internal/shared/types"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_Diff(t *testing.T) {
+	tests := map[string]struct {
+		local    types.AppManifest
+		remote   types.AppManifest
+		expected []FieldDiff
+	}{
+		"identical manifests produce no diffs": {
+			local: types.AppManifest{
+				DisplayInformation: types.DisplayInformation{Name: "App"},
+			},
+			remote: types.AppManifest{
+				DisplayInformation: types.DisplayInformation{Name: "App"},
+			},
+			expected: nil,
+		},
+		"modified field detected": {
+			local: types.AppManifest{
+				DisplayInformation: types.DisplayInformation{Name: "App", Description: "Local desc"},
+			},
+			remote: types.AppManifest{
+				DisplayInformation: types.DisplayInformation{Name: "App", Description: "Remote desc"},
+			},
+			expected: []FieldDiff{
+				{Path: "display_information.description", Type: DiffModified, LocalValue: "Local desc", RemoteValue: "Remote desc"},
+			},
+		},
+		"local-only field detected": {
+			local: types.AppManifest{
+				DisplayInformation: types.DisplayInformation{Name: "App", Description: "Has desc"},
+			},
+			remote: types.AppManifest{
+				DisplayInformation: types.DisplayInformation{Name: "App"},
+			},
+			expected: []FieldDiff{
+				{Path: "display_information.description", Type: DiffLocalOnly, LocalValue: "Has desc"},
+			},
+		},
+		"remote-only field detected": {
+			local: types.AppManifest{
+				DisplayInformation: types.DisplayInformation{Name: "App"},
+			},
+			remote: types.AppManifest{
+				DisplayInformation: types.DisplayInformation{Name: "App", Description: "Remote only"},
+			},
+			expected: []FieldDiff{
+				{Path: "display_information.description", Type: DiffRemoteOnly, RemoteValue: "Remote only"},
+			},
+		},
+		"function added locally": {
+			local: types.AppManifest{
+				DisplayInformation: types.DisplayInformation{Name: "App"},
+				Functions: map[string]types.ManifestFunction{
+					"greet": {Title: "Greet", Description: "Hello"},
+				},
+			},
+			remote: types.AppManifest{
+				DisplayInformation: types.DisplayInformation{Name: "App"},
+			},
+			expected: []FieldDiff{
+				{Path: "functions.greet.description", Type: DiffLocalOnly, LocalValue: "Hello"},
+				{Path: "functions.greet.title", Type: DiffLocalOnly, LocalValue: "Greet"},
+			},
+		},
+		"array values compared as wholes": {
+			local: types.AppManifest{
+				DisplayInformation: types.DisplayInformation{Name: "App"},
+				OAuthConfig: &types.OAuthConfig{
+					Scopes: &types.ManifestScopes{
+						Bot: []string{"chat:write", "users:read"},
+					},
+				},
+			},
+			remote: types.AppManifest{
+				DisplayInformation: types.DisplayInformation{Name: "App"},
+				OAuthConfig: &types.OAuthConfig{
+					Scopes: &types.ManifestScopes{
+						Bot: []string{"chat:write", "files:read"},
+					},
+				},
+			},
+			expected: []FieldDiff{
+				{
+					Path:        "oauth_config.scopes.bot",
+					Type:        DiffModified,
+					LocalValue:  []any{"chat:write", "users:read"},
+					RemoteValue: []any{"chat:write", "files:read"},
+				},
+			},
+		},
+	}
+	for name, tc := range tests {
+		t.Run(name, func(t *testing.T) {
+			result, err := Diff(tc.local, tc.remote)
+			require.NoError(t, err)
+			if tc.expected == nil {
+				assert.False(t, result.HasDifferences())
+				return
+			}
+			assert.True(t, result.HasDifferences())
+			for _, expectedDiff := range tc.expected {
+				found := false
+				for _, actualDiff := range result.Diffs {
+					if actualDiff.Path == expectedDiff.Path {
+						found = true
+						assert.Equal(t, expectedDiff.Type, actualDiff.Type, "diff type mismatch for path %s", expectedDiff.Path)
+						if expectedDiff.LocalValue != nil {
+							assert.Equal(t, expectedDiff.LocalValue, actualDiff.LocalValue, "local value mismatch for path %s", expectedDiff.Path)
+						}
+						if expectedDiff.RemoteValue != nil {
+							assert.Equal(t, expectedDiff.RemoteValue, actualDiff.RemoteValue, "remote value mismatch for path %s", expectedDiff.Path)
+						}
+						break
+					}
+				}
+				assert.True(t, found, "expected diff not found for path %s", expectedDiff.Path)
+			}
+		})
+	}
+}
+
+func Test_DiffResult_HasDifferences(t *testing.T) {
+	t.Run("empty result has no differences", func(t *testing.T) {
+		result := &DiffResult{}
+		assert.False(t, result.HasDifferences())
+	})
+
+	t.Run("result with diffs has differences", func(t *testing.T) {
+		result := &DiffResult{
+			Diffs: []FieldDiff{{Path: "test", Type: DiffModified}},
+		}
+		assert.True(t, result.HasDifferences())
+	})
+}