feat(pass): add --force flag to set command

Adds a --force/-f flag to `docker pass set` that routes through
store.Upsert instead of store.Save, allowing callers to overwrite an
existing secret atomically on every platform. Without --force the
default Save behavior is preserved (errors on macOS when the secret
already exists; silently overwrites on Linux and Windows). Documents
the platform-dependent overwrite semantics in the command's Long
description.

Author: joe0BAB

plugins/pass/command_test.go

@@ -135,6 +135,33 @@ func Test_rootCommand(t *testing.T) {
 			assert.ErrorIs(t, err, errInvalidID)
 			assert.Equal(t, "Error: "+errInvalidID.Error()+"\n", out)
 		})
+		t.Run("--force overwrites existing secret", func(t *testing.T) {
+			// Make Save return an error so the test fails if --force does not
+			// route the call through Upsert.
+			mock := teststore.NewMockStore(
+				teststore.WithStore(map[store.ID]store.Secret{
+					store.MustParseID("foo"): pass.NewPassValue([]byte("old")),
+				}),
+				teststore.WithStoreSaveErr(errors.New("save should not be called when --force is set")),
+			)
+			out, err := executeCommand(Root(t.Context(), mock, mockInfo), "set", "foo=new", "--force")
+			assert.NoError(t, err)
+			assert.Empty(t, out)
+			s, err := mock.Get(t.Context(), secrets.MustParseID("foo"))
+			require.NoError(t, err)
+			impl, ok := s.(*pass.PassValue)
+			require.True(t, ok)
+			v, err := impl.Marshal()
+			require.NoError(t, err)
+			assert.Equal(t, "new", string(v))
+		})
+		t.Run("--force surfaces upsert error", func(t *testing.T) {
+			errUpsert := errors.New("upsert error")
+			mock := teststore.NewMockStore(teststore.WithStoreUpsertErr(errUpsert))
+			out, err := executeCommand(Root(t.Context(), mock, mockInfo), "set", "foo=bar", "--force")
+			assert.ErrorIs(t, errUpsert, err)
+			assert.Equal(t, "Error: "+errUpsert.Error()+"\n", out)
+		})
 	})
 	t.Run("list", func(t *testing.T) {
 		t.Run("ok", func(t *testing.T) {

plugins/pass/commands/set.go

@@ -42,10 +42,14 @@ docker pass set POSTGRES_PASSWORD=my-secret-password --metadata owner=alice --me
 
 ### Or pass a JSON payload with secret and metadata via STDIN:
 echo '{"secret":"my-secret-password","metadata":{"owner":"alice"}}' | docker pass set POSTGRES_PASSWORD
+
+### Overwrite an existing secret:
+docker pass set POSTGRES_PASSWORD=new-secret-password --force
 `
 
 type setOpts struct {
 	metadata []string // raw "key=value" strings from --metadata flag
+	force    bool     // if true, overwrite existing secret instead of erroring
 }
 
 type stdinPayload struct {
@@ -59,8 +63,16 @@ func SetCommand(kc store.Store) *cobra.Command {
 		Use:     "set id[=value]",
 		Aliases: []string{"store", "save"},
 		Short:   "Set a secret",
-		Long: `Stores a secret in the local OS keychain. The secret value can be
-provided inline (NAME=VALUE) or piped via STDIN.`,
+		Long: `Stores a secret in the local OS keychain. The secret value can be provided inline (NAME=VALUE) or piped via STDIN.
+
+Behavior when a secret with the same id already exists is platform-dependent:
+  - macOS (Keychain): the command fails with a duplicate-item error.
+  - Linux (Secret Service) and Windows (Credential Manager): the existing
+    value is silently overwritten.
+
+Pass --force to overwrite an existing secret on every platform. With --force
+the secret is replaced atomically, so concurrent reads never observe a missing
+value.`,
 		Example: strings.Trim(setExample, "\n"),
 		Args:    cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -106,11 +118,15 @@ provided inline (NAME=VALUE) or piped via STDIN.`,
 					return err
 				}
 			}
+			if opts.force {
+				return kc.Upsert(cmd.Context(), id, pv)
+			}
 			return kc.Save(cmd.Context(), id, pv)
 		},
 	}
 	flags := cmd.Flags()
 	flags.StringArrayVar(&opts.metadata, "metadata", nil, "Non-sensitive key=value metadata (repeatable)")
+	flags.BoolVarP(&opts.force, "force", "f", false, "Overwrite existing secret if it already exists")
 	return cmd
 }