From dbe605be7f50b0c0a9b03b67f6eb4cbea55680a6 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Wed, 27 Dec 2023 07:06:58 +0000
Subject: [PATCH 01/17] chore(ux): improve error output for unknown spec flag

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/remote.go |  5 +-
 cmd/oras/internal/option/spec.go   | 75 +++++++++++++++++++++---------
 2 files changed, 55 insertions(+), 25 deletions(-)

diff --git a/cmd/oras/internal/option/remote.go b/cmd/oras/internal/option/remote.go
index 26c01fc90..5547569e5 100644
--- a/cmd/oras/internal/option/remote.go
+++ b/cmd/oras/internal/option/remote.go
@@ -116,10 +116,7 @@ func (opts *Remote) Parse() error {
 	if err := opts.parseCustomHeaders(); err != nil {
 		return err
 	}
-	if err := opts.readPassword(); err != nil {
-		return err
-	}
-	return opts.DistributionSpec.Parse()
+	return opts.readPassword()
 }
 
 // readPassword tries to read password with optional cmd prompt.
diff --git a/cmd/oras/internal/option/spec.go b/cmd/oras/internal/option/spec.go
index 965eb929b..015c54b76 100644
--- a/cmd/oras/internal/option/spec.go
+++ b/cmd/oras/internal/option/spec.go
@@ -20,11 +20,14 @@ import (
 
 	"github.com/spf13/pflag"
 	"oras.land/oras-go/v2"
+	oerrors "oras.land/oras/cmd/oras/internal/errors"
 )
 
 const (
-	ImageSpecV1_1 = "v1.1"
-	ImageSpecV1_0 = "v1.0"
+	ImageSpecV1_1    = "v1.1"
+	ImageSpecV1_0    = "v1.0"
+	ReferrersTagV1_1 = "v1.1-referrers-tag"
+	ReferrersAPIV1_1 = "v1.1-referrers-api"
 )
 
 // ImageSpec option struct.
@@ -33,22 +36,37 @@ type ImageSpec struct {
 	PackVersion oras.PackManifestVersion
 }
 
-// Parse parses flags into the option.
-func (opts *ImageSpec) Parse() error {
-	switch opts.flag {
-	case ImageSpecV1_1:
-		opts.PackVersion = oras.PackManifestVersion1_1_RC4
+// Set validates and sets the flag value from a string argument.
+func (i *ImageSpec) Set(value string) error {
+	i.flag = value
+	switch value {
+	case ImageSpecV1_1, "":
+		// default to v1.1
+		i.PackVersion = oras.PackManifestVersion1_1_RC4
 	case ImageSpecV1_0:
-		opts.PackVersion = oras.PackManifestVersion1_0
+		i.PackVersion = oras.PackManifestVersion1_0
 	default:
-		return fmt.Errorf("unknown image specification flag: %q", opts.flag)
+		return &oerrors.Error{
+			Err:            fmt.Errorf("unknown image specification flag: %s", value),
+			Recommendation: fmt.Sprintf("Available options: %s", i.Type()),
+		}
 	}
 	return nil
 }
 
+// Type returns the type of the flag.
+func (i *ImageSpec) Type() string {
+	return fmt.Sprintf("%s, %s", ImageSpecV1_1, ImageSpecV1_0)
+}
+
+// String returns the string representation of the flag.
+func (i *ImageSpec) String() string {
+	return i.flag
+}
+
 // ApplyFlags applies flags to a command flag set.
 func (opts *ImageSpec) ApplyFlags(fs *pflag.FlagSet) {
-	fs.StringVar(&opts.flag, "image-spec", ImageSpecV1_1, fmt.Sprintf("[Experimental] specify manifest type for building artifact. options: %s, %s", ImageSpecV1_1, ImageSpecV1_0))
+	fs.Var(opts, "image-spec", "[Experimental] specify manifest type for building artifact")
 }
 
 // DistributionSpec option struct.
@@ -58,28 +76,43 @@ type DistributionSpec struct {
 	ReferrersAPI *bool
 
 	// specFlag should be provided in form of`<version>-<api>-<option>`
-	specFlag string
+	flag string
 }
 
-// Parse parses flags into the option.
-func (opts *DistributionSpec) Parse() error {
-	switch opts.specFlag {
+// Set validates and sets the flag value from a string argument.
+func (d *DistributionSpec) Set(value string) error {
+	d.flag = value
+	switch d.flag {
 	case "":
-		opts.ReferrersAPI = nil
-	case "v1.1-referrers-tag":
+		// default to unknown
+		d.ReferrersAPI = nil
+	case ReferrersTagV1_1:
 		isApi := false
-		opts.ReferrersAPI = &isApi
-	case "v1.1-referrers-api":
+		d.ReferrersAPI = &isApi
+	case ReferrersAPIV1_1:
 		isApi := true
-		opts.ReferrersAPI = &isApi
+		d.ReferrersAPI = &isApi
 	default:
-		return fmt.Errorf("unknown distribution specification flag: %q", opts.specFlag)
+		return &oerrors.Error{
+			Err:            fmt.Errorf("unknown distribution specification flag: %s", value),
+			Recommendation: fmt.Sprintf("Available options: %s", d.Type()),
+		}
 	}
 	return nil
 }
 
+// Type returns the type of the flag.
+func (d *DistributionSpec) Type() string {
+	return fmt.Sprintf("%s, %s", ReferrersTagV1_1, ReferrersAPIV1_1)
+}
+
+// String returns the string representation of the flag.
+func (d *DistributionSpec) String() string {
+	return d.flag
+}
+
 // ApplyFlagsWithPrefix applies flags to a command flag set with a prefix string.
 func (opts *DistributionSpec) ApplyFlagsWithPrefix(fs *pflag.FlagSet, prefix, description string) {
 	flagPrefix, notePrefix := applyPrefix(prefix, description)
-	fs.StringVar(&opts.specFlag, flagPrefix+"distribution-spec", "", "[Preview] set OCI distribution spec version and API option for "+notePrefix+"target. options: v1.1-referrers-api, v1.1-referrers-tag")
+	fs.Var(opts, flagPrefix+"distribution-spec", "[Preview] set OCI distribution spec version and API option for "+notePrefix+"target. options: v1.1-referrers-api, v1.1-referrers-tag")
 }

From a77ff5c1a5e34d625952b3763f9e4d6dea351c30 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Wed, 27 Dec 2023 08:02:04 +0000
Subject: [PATCH 02/17] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/spec.go | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/cmd/oras/internal/option/spec.go b/cmd/oras/internal/option/spec.go
index 015c54b76..b4939b2a1 100644
--- a/cmd/oras/internal/option/spec.go
+++ b/cmd/oras/internal/option/spec.go
@@ -40,8 +40,7 @@ type ImageSpec struct {
 func (i *ImageSpec) Set(value string) error {
 	i.flag = value
 	switch value {
-	case ImageSpecV1_1, "":
-		// default to v1.1
+	case ImageSpecV1_1:
 		i.PackVersion = oras.PackManifestVersion1_1_RC4
 	case ImageSpecV1_0:
 		i.PackVersion = oras.PackManifestVersion1_0
@@ -66,6 +65,8 @@ func (i *ImageSpec) String() string {
 
 // ApplyFlags applies flags to a command flag set.
 func (opts *ImageSpec) ApplyFlags(fs *pflag.FlagSet) {
+	// default to v1.1-rc.4
+	opts.PackVersion = oras.PackManifestVersion1_1_RC4
 	fs.Var(opts, "image-spec", "[Experimental] specify manifest type for building artifact")
 }
 
@@ -83,9 +84,6 @@ type DistributionSpec struct {
 func (d *DistributionSpec) Set(value string) error {
 	d.flag = value
 	switch d.flag {
-	case "":
-		// default to unknown
-		d.ReferrersAPI = nil
 	case ReferrersTagV1_1:
 		isApi := false
 		d.ReferrersAPI = &isApi

From a64c84d52d0e04c25cedbcbb521af2278c32f8b9 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Wed, 27 Dec 2023 08:32:46 +0000
Subject: [PATCH 03/17] add e2e tests adnd default value

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/spec.go |  4 ++--
 test/e2e/internal/utils/flags.go | 10 +++++++---
 test/e2e/suite/command/attach.go | 12 ++++++++++++
 test/e2e/suite/command/push.go   | 10 ++++++++++
 4 files changed, 31 insertions(+), 5 deletions(-)

diff --git a/cmd/oras/internal/option/spec.go b/cmd/oras/internal/option/spec.go
index b4939b2a1..84e2796ef 100644
--- a/cmd/oras/internal/option/spec.go
+++ b/cmd/oras/internal/option/spec.go
@@ -67,7 +67,7 @@ func (i *ImageSpec) String() string {
 func (opts *ImageSpec) ApplyFlags(fs *pflag.FlagSet) {
 	// default to v1.1-rc.4
 	opts.PackVersion = oras.PackManifestVersion1_1_RC4
-	fs.Var(opts, "image-spec", "[Experimental] specify manifest type for building artifact")
+	fs.Var(opts, "image-spec", `[Experimental] specify manifest type for building artifact (default "v1.1")`)
 }
 
 // DistributionSpec option struct.
@@ -112,5 +112,5 @@ func (d *DistributionSpec) String() string {
 // ApplyFlagsWithPrefix applies flags to a command flag set with a prefix string.
 func (opts *DistributionSpec) ApplyFlagsWithPrefix(fs *pflag.FlagSet, prefix, description string) {
 	flagPrefix, notePrefix := applyPrefix(prefix, description)
-	fs.Var(opts, flagPrefix+"distribution-spec", "[Preview] set OCI distribution spec version and API option for "+notePrefix+"target. options: v1.1-referrers-api, v1.1-referrers-tag")
+	fs.Var(opts, flagPrefix+"distribution-spec", "[Preview] set OCI distribution spec version and API option for "+notePrefix+"target.")
 }
diff --git a/test/e2e/internal/utils/flags.go b/test/e2e/internal/utils/flags.go
index 8263e49f9..893fa575d 100644
--- a/test/e2e/internal/utils/flags.go
+++ b/test/e2e/internal/utils/flags.go
@@ -16,11 +16,15 @@ limitations under the License.
 package utils
 
 var Flags = struct {
-	Layout     string
-	FromLayout string
-	ToLayout   string
+	Layout           string
+	FromLayout       string
+	ToLayout         string
+	DistributionSpec string
+	ImageSpec        string
 }{
 	"--oci-layout",
 	"--from-oci-layout",
 	"--to-oci-layout",
+	"--distribution-spec",
+	"--image-spec",
 }
diff --git a/test/e2e/suite/command/attach.go b/test/e2e/suite/command/attach.go
index 63fc1fea4..269337b04 100644
--- a/test/e2e/suite/command/attach.go
+++ b/test/e2e/suite/command/attach.go
@@ -72,6 +72,18 @@ var _ = Describe("ORAS beginners:", func() {
 			gomega.Expect(err).Should(gbytes.Say("\n"))
 			gomega.Expect(err).Should(gbytes.Say(`Run "oras attach -h"`))
 		})
+
+		It("should fail if distribution spec is not valid", func() {
+			testRepo := attachTestRepo("invalid-image-spec")
+			CopyZOTRepo(ImageRepo, testRepo)
+			subjectRef := RegistryRef(ZOTHost, testRepo, foobar.Tag)
+			invalidFlag := "???"
+			ORAS("attach", "--artifact-type", "test/attach", subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia), Flags.DistributionSpec, invalidFlag).
+				ExpectFailure().
+				WithWorkDir(PrepareTempFiles()).
+				MatchErrKeyWords("Error:", invalidFlag, "Available options: v1.1-referrers-tag, v1.1-referrers-api").
+				Exec()
+		})
 	})
 })
 
diff --git a/test/e2e/suite/command/push.go b/test/e2e/suite/command/push.go
index 123f6a0bd..56070ab3a 100644
--- a/test/e2e/suite/command/push.go
+++ b/test/e2e/suite/command/push.go
@@ -56,6 +56,16 @@ var _ = Describe("ORAS beginners:", func() {
 
 			ORAS("push", ref, "--config", foobar.FileConfigName, "--artifact-type", "test/artifact+json", "--image-spec", "v1.0").ExpectFailure().WithWorkDir(tempDir).Exec()
 		})
+
+		It("should fail if image spec is not valid", Focus, func() {
+			testRepo := attachTestRepo("invalid-image-spec")
+			subjectRef := RegistryRef(ZOTHost, testRepo, foobar.Tag)
+			invalidFlag := "???"
+			ORAS("push", subjectRef, Flags.ImageSpec, invalidFlag).
+				ExpectFailure().
+				MatchErrKeyWords("Error:", invalidFlag, "Available options: v1.1, v1.0").
+				Exec()
+		})
 	})
 })
 

From 649619f871a2a3fd152bc226d5f040c4e430d8a2 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Wed, 27 Dec 2023 08:35:32 +0000
Subject: [PATCH 04/17] remove focus spec

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/suite/command/push.go | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/e2e/suite/command/push.go b/test/e2e/suite/command/push.go
index 56070ab3a..d92ab02f8 100644
--- a/test/e2e/suite/command/push.go
+++ b/test/e2e/suite/command/push.go
@@ -57,7 +57,7 @@ var _ = Describe("ORAS beginners:", func() {
 			ORAS("push", ref, "--config", foobar.FileConfigName, "--artifact-type", "test/artifact+json", "--image-spec", "v1.0").ExpectFailure().WithWorkDir(tempDir).Exec()
 		})
 
-		It("should fail if image spec is not valid", Focus, func() {
+		It("should fail if image spec is not valid", func() {
 			testRepo := attachTestRepo("invalid-image-spec")
 			subjectRef := RegistryRef(ZOTHost, testRepo, foobar.Tag)
 			invalidFlag := "???"

From 830ecc936c139fdeb52ce0df64118346edd959ba Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Wed, 27 Dec 2023 08:40:23 +0000
Subject: [PATCH 05/17] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/suite/command/cp.go       | 4 ++--
 test/e2e/suite/command/manifest.go | 4 ++--
 test/e2e/suite/command/push.go     | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/test/e2e/suite/command/cp.go b/test/e2e/suite/command/cp.go
index 45718fa29..b4741a32c 100644
--- a/test/e2e/suite/command/cp.go
+++ b/test/e2e/suite/command/cp.go
@@ -43,9 +43,9 @@ var _ = Describe("ORAS beginners:", func() {
 	When("running cp command", func() {
 		It("should show help doc with feature flags", func() {
 			out := ORAS("cp", "--help").MatchKeyWords("Copy", ExampleDesc).Exec()
-			Expect(out).Should(gbytes.Say("--from-distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			Expect(out).Should(gbytes.Say("--from-distribution-spec \\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 			Expect(out).Should(gbytes.Say("-r, --recursive\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
-			Expect(out).Should(gbytes.Say("--to-distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			Expect(out).Should(gbytes.Say("--to-distribution-spec \\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 		})
 
 		It("should fail when no reference provided", func() {
diff --git a/test/e2e/suite/command/manifest.go b/test/e2e/suite/command/manifest.go
index 6f7c10ebc..22ac5d736 100644
--- a/test/e2e/suite/command/manifest.go
+++ b/test/e2e/suite/command/manifest.go
@@ -54,7 +54,7 @@ var _ = Describe("ORAS beginners:", func() {
 		When("running `manifest push`", func() {
 			It("should show help doc with feature flags", func() {
 				out := ORAS("manifest", "push", "--help").MatchKeyWords(ExampleDesc).Exec()
-				gomega.Expect(out).Should(gbytes.Say("--distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+				gomega.Expect(out).Should(gbytes.Say("--distribution-spec \\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 			})
 
 			It("should have flag for prettifying JSON output", func() {
@@ -98,7 +98,7 @@ var _ = Describe("ORAS beginners:", func() {
 		When("running `manifest delete`", func() {
 			It("should show help doc with feature flags", func() {
 				out := ORAS("manifest", "delete", "--help").MatchKeyWords(ExampleDesc).Exec()
-				gomega.Expect(out).Should(gbytes.Say("--distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+				gomega.Expect(out).Should(gbytes.Say("--distribution-spec \\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 			})
 
 			It("should fail and show detailed error description if no argument provided", func() {
diff --git a/test/e2e/suite/command/push.go b/test/e2e/suite/command/push.go
index d92ab02f8..b6a362634 100644
--- a/test/e2e/suite/command/push.go
+++ b/test/e2e/suite/command/push.go
@@ -38,7 +38,7 @@ var _ = Describe("ORAS beginners:", func() {
 	When("running push command", func() {
 		It("should show help description with feature flags", func() {
 			out := ORAS("push", "--help").MatchKeyWords(ExampleDesc).Exec().Out
-			gomega.Expect(out).Should(gbytes.Say("--image-spec string\\s+%s", regexp.QuoteMeta(feature.Experimental.Mark)))
+			gomega.Expect(out).Should(gbytes.Say("--image-spec \\s+%s", regexp.QuoteMeta(feature.Experimental.Mark)))
 		})
 
 		It("should fail and show detailed error description if no argument provided", func() {

From 8283f8f57316e0f0d0157d26b70dcb3532c6df82 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Wed, 27 Dec 2023 12:10:36 +0000
Subject: [PATCH 06/17] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/suite/command/attach.go   | 2 +-
 test/e2e/suite/command/discover.go | 2 +-
 test/e2e/suite/command/manifest.go | 4 ++--
 test/e2e/suite/command/push.go     | 2 +-
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/test/e2e/suite/command/attach.go b/test/e2e/suite/command/attach.go
index 269337b04..b83855653 100644
--- a/test/e2e/suite/command/attach.go
+++ b/test/e2e/suite/command/attach.go
@@ -42,7 +42,7 @@ var _ = Describe("ORAS beginners:", func() {
 
 		It("should show preview and help doc", func() {
 			out := ORAS("attach", "--help").MatchKeyWords(feature.Preview.Mark+" Attach", feature.Preview.Description, ExampleDesc).Exec()
-			gomega.Expect(out).Should(gbytes.Say("--distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			gomega.Expect(out).Should(gbytes.Say("--distribution-spec v1.1-referrers-tag, v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 		})
 
 		It("should fail when no subject reference provided", func() {
diff --git a/test/e2e/suite/command/discover.go b/test/e2e/suite/command/discover.go
index fd2f678f5..2989a07f5 100644
--- a/test/e2e/suite/command/discover.go
+++ b/test/e2e/suite/command/discover.go
@@ -53,7 +53,7 @@ var _ = Describe("ORAS beginners:", func() {
 
 		It("should show preview and help doc", func() {
 			out := ORAS("discover", "--help").MatchKeyWords(feature.Preview.Mark+" Discover", feature.Preview.Description, ExampleDesc).Exec()
-			gomega.Expect(out).Should(gbytes.Say("--distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			gomega.Expect(out).Should(gbytes.Say("--distribution-spec v1.1-referrers-tag, v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 		})
 
 		It("should fail when no subject reference provided", func() {
diff --git a/test/e2e/suite/command/manifest.go b/test/e2e/suite/command/manifest.go
index 22ac5d736..8e456e74e 100644
--- a/test/e2e/suite/command/manifest.go
+++ b/test/e2e/suite/command/manifest.go
@@ -54,7 +54,7 @@ var _ = Describe("ORAS beginners:", func() {
 		When("running `manifest push`", func() {
 			It("should show help doc with feature flags", func() {
 				out := ORAS("manifest", "push", "--help").MatchKeyWords(ExampleDesc).Exec()
-				gomega.Expect(out).Should(gbytes.Say("--distribution-spec \\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+				gomega.Expect(out).Should(gbytes.Say("--distribution-spec v1.1-referrers-tag, v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 			})
 
 			It("should have flag for prettifying JSON output", func() {
@@ -98,7 +98,7 @@ var _ = Describe("ORAS beginners:", func() {
 		When("running `manifest delete`", func() {
 			It("should show help doc with feature flags", func() {
 				out := ORAS("manifest", "delete", "--help").MatchKeyWords(ExampleDesc).Exec()
-				gomega.Expect(out).Should(gbytes.Say("--distribution-spec \\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+				gomega.Expect(out).Should(gbytes.Say("--distribution-spec v1.1-referrers-tag, v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 			})
 
 			It("should fail and show detailed error description if no argument provided", func() {
diff --git a/test/e2e/suite/command/push.go b/test/e2e/suite/command/push.go
index b6a362634..7338dd297 100644
--- a/test/e2e/suite/command/push.go
+++ b/test/e2e/suite/command/push.go
@@ -38,7 +38,7 @@ var _ = Describe("ORAS beginners:", func() {
 	When("running push command", func() {
 		It("should show help description with feature flags", func() {
 			out := ORAS("push", "--help").MatchKeyWords(ExampleDesc).Exec().Out
-			gomega.Expect(out).Should(gbytes.Say("--image-spec \\s+%s", regexp.QuoteMeta(feature.Experimental.Mark)))
+			gomega.Expect(out).Should(gbytes.Say("--image-spec v1.1, v1.0\\s+%s", regexp.QuoteMeta(feature.Experimental.Mark)))
 		})
 
 		It("should fail and show detailed error description if no argument provided", func() {

From 41913d13e13ea690066c1c2394bfc54a23344aa4 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Wed, 27 Dec 2023 12:28:51 +0000
Subject: [PATCH 07/17] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/suite/command/cp.go | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/test/e2e/suite/command/cp.go b/test/e2e/suite/command/cp.go
index b4741a32c..ce397fed7 100644
--- a/test/e2e/suite/command/cp.go
+++ b/test/e2e/suite/command/cp.go
@@ -43,9 +43,9 @@ var _ = Describe("ORAS beginners:", func() {
 	When("running cp command", func() {
 		It("should show help doc with feature flags", func() {
 			out := ORAS("cp", "--help").MatchKeyWords("Copy", ExampleDesc).Exec()
-			Expect(out).Should(gbytes.Say("--from-distribution-spec \\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			Expect(out).Should(gbytes.Say("--from-distribution-spec  v1.1-referrers-tag, v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 			Expect(out).Should(gbytes.Say("-r, --recursive\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
-			Expect(out).Should(gbytes.Say("--to-distribution-spec \\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			Expect(out).Should(gbytes.Say("--to-distribution-spec  v1.1-referrers-tag, v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 		})
 
 		It("should fail when no reference provided", func() {

From 83d68435f7fb4f9bd1632de4cfe932d061e8208e Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Wed, 27 Dec 2023 12:33:27 +0000
Subject: [PATCH 08/17] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/suite/command/cp.go | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/test/e2e/suite/command/cp.go b/test/e2e/suite/command/cp.go
index ce397fed7..a6fc33fd9 100644
--- a/test/e2e/suite/command/cp.go
+++ b/test/e2e/suite/command/cp.go
@@ -43,9 +43,9 @@ var _ = Describe("ORAS beginners:", func() {
 	When("running cp command", func() {
 		It("should show help doc with feature flags", func() {
 			out := ORAS("cp", "--help").MatchKeyWords("Copy", ExampleDesc).Exec()
-			Expect(out).Should(gbytes.Say("--from-distribution-spec  v1.1-referrers-tag, v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			Expect(out).Should(gbytes.Say("--from-distribution-spec v1.1-referrers-tag, v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 			Expect(out).Should(gbytes.Say("-r, --recursive\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
-			Expect(out).Should(gbytes.Say("--to-distribution-spec  v1.1-referrers-tag, v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			Expect(out).Should(gbytes.Say("--to-distribution-spec v1.1-referrers-tag, v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 		})
 
 		It("should fail when no reference provided", func() {

From 2d4f38314e8b610a31965101e6cdce6a5e57d805 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Thu, 28 Dec 2023 05:44:37 +0000
Subject: [PATCH 09/17] resolve comment

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/spec.go | 67 ++++++++++++++++----------------
 1 file changed, 34 insertions(+), 33 deletions(-)

diff --git a/cmd/oras/internal/option/spec.go b/cmd/oras/internal/option/spec.go
index 84e2796ef..4769743de 100644
--- a/cmd/oras/internal/option/spec.go
+++ b/cmd/oras/internal/option/spec.go
@@ -17,6 +17,7 @@ package option
 
 import (
 	"fmt"
+	"strings"
 
 	"github.com/spf13/pflag"
 	"oras.land/oras-go/v2"
@@ -24,53 +25,53 @@ import (
 )
 
 const (
-	ImageSpecV1_1    = "v1.1"
-	ImageSpecV1_0    = "v1.0"
-	ReferrersTagV1_1 = "v1.1-referrers-tag"
-	ReferrersAPIV1_1 = "v1.1-referrers-api"
+	ImageSpecV1_1                    = "v1.1"
+	ImageSpecV1_0                    = "v1.0"
+	DistributionSpecReferrersTagV1_1 = "v1.1-referrers-tag"
+	ReferrersAPIV1_1                 = "v1.1-referrers-api"
 )
 
-// ImageSpec option struct.
+// ImageSpec option struct which implements pflag.Value interface.
 type ImageSpec struct {
 	flag        string
 	PackVersion oras.PackManifestVersion
 }
 
 // Set validates and sets the flag value from a string argument.
-func (i *ImageSpec) Set(value string) error {
-	i.flag = value
+func (is *ImageSpec) Set(value string) error {
+	is.flag = value
 	switch value {
 	case ImageSpecV1_1:
-		i.PackVersion = oras.PackManifestVersion1_1_RC4
+		is.PackVersion = oras.PackManifestVersion1_1_RC4
 	case ImageSpecV1_0:
-		i.PackVersion = oras.PackManifestVersion1_0
+		is.PackVersion = oras.PackManifestVersion1_0
 	default:
 		return &oerrors.Error{
 			Err:            fmt.Errorf("unknown image specification flag: %s", value),
-			Recommendation: fmt.Sprintf("Available options: %s", i.Type()),
+			Recommendation: fmt.Sprintf("Available options: %s", is.Type()),
 		}
 	}
 	return nil
 }
 
-// Type returns the type of the flag.
-func (i *ImageSpec) Type() string {
-	return fmt.Sprintf("%s, %s", ImageSpecV1_1, ImageSpecV1_0)
+// Type returns the string value of the inner flag.
+func (is *ImageSpec) Type() string {
+	return strings.Join([]string{ImageSpecV1_1, ImageSpecV1_0}, ",")
 }
 
 // String returns the string representation of the flag.
-func (i *ImageSpec) String() string {
-	return i.flag
+func (is *ImageSpec) String() string {
+	return is.flag
 }
 
 // ApplyFlags applies flags to a command flag set.
-func (opts *ImageSpec) ApplyFlags(fs *pflag.FlagSet) {
+func (is *ImageSpec) ApplyFlags(fs *pflag.FlagSet) {
 	// default to v1.1-rc.4
-	opts.PackVersion = oras.PackManifestVersion1_1_RC4
-	fs.Var(opts, "image-spec", `[Experimental] specify manifest type for building artifact (default "v1.1")`)
+	is.PackVersion = oras.PackManifestVersion1_1_RC4
+	fs.Var(is, "image-spec", `[Experimental] specify manifest type for building artifact (default "v1.1")`)
 }
 
-// DistributionSpec option struct.
+// DistributionSpec option struct which implements pflag.Value interface.
 type DistributionSpec struct {
 	// ReferrersAPI indicates the preference of the implementation of the Referrers API.
 	// Set to true for referrers API, false for referrers tag scheme, and nil for auto fallback.
@@ -81,36 +82,36 @@ type DistributionSpec struct {
 }
 
 // Set validates and sets the flag value from a string argument.
-func (d *DistributionSpec) Set(value string) error {
-	d.flag = value
-	switch d.flag {
-	case ReferrersTagV1_1:
+func (ds *DistributionSpec) Set(value string) error {
+	ds.flag = value
+	switch ds.flag {
+	case DistributionSpecReferrersTagV1_1:
 		isApi := false
-		d.ReferrersAPI = &isApi
+		ds.ReferrersAPI = &isApi
 	case ReferrersAPIV1_1:
 		isApi := true
-		d.ReferrersAPI = &isApi
+		ds.ReferrersAPI = &isApi
 	default:
 		return &oerrors.Error{
 			Err:            fmt.Errorf("unknown distribution specification flag: %s", value),
-			Recommendation: fmt.Sprintf("Available options: %s", d.Type()),
+			Recommendation: fmt.Sprintf("Available options: %s", ds.Type()),
 		}
 	}
 	return nil
 }
 
-// Type returns the type of the flag.
-func (d *DistributionSpec) Type() string {
-	return fmt.Sprintf("%s, %s", ReferrersTagV1_1, ReferrersAPIV1_1)
+// Type returns the string value of the inner flag.
+func (ds *DistributionSpec) Type() string {
+	return strings.Join([]string{DistributionSpecReferrersTagV1_1, ReferrersAPIV1_1}, ",")
 }
 
 // String returns the string representation of the flag.
-func (d *DistributionSpec) String() string {
-	return d.flag
+func (ds *DistributionSpec) String() string {
+	return ds.flag
 }
 
 // ApplyFlagsWithPrefix applies flags to a command flag set with a prefix string.
-func (opts *DistributionSpec) ApplyFlagsWithPrefix(fs *pflag.FlagSet, prefix, description string) {
+func (ds *DistributionSpec) ApplyFlagsWithPrefix(fs *pflag.FlagSet, prefix, description string) {
 	flagPrefix, notePrefix := applyPrefix(prefix, description)
-	fs.Var(opts, flagPrefix+"distribution-spec", "[Preview] set OCI distribution spec version and API option for "+notePrefix+"target.")
+	fs.Var(ds, flagPrefix+"distribution-spec", "[Preview] set OCI distribution spec version and API option for "+notePrefix+"target.")
 }

From 35e960ee8a447835ed17cae3fddf01c7b08395c7 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Thu, 28 Dec 2023 05:45:12 +0000
Subject: [PATCH 10/17] resolve comment

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/spec.go | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/cmd/oras/internal/option/spec.go b/cmd/oras/internal/option/spec.go
index 4769743de..fcf4b8adb 100644
--- a/cmd/oras/internal/option/spec.go
+++ b/cmd/oras/internal/option/spec.go
@@ -28,7 +28,7 @@ const (
 	ImageSpecV1_1                    = "v1.1"
 	ImageSpecV1_0                    = "v1.0"
 	DistributionSpecReferrersTagV1_1 = "v1.1-referrers-tag"
-	ReferrersAPIV1_1                 = "v1.1-referrers-api"
+	DistributionSpecReferrersAPIV1_1 = "v1.1-referrers-api"
 )
 
 // ImageSpec option struct which implements pflag.Value interface.
@@ -88,7 +88,7 @@ func (ds *DistributionSpec) Set(value string) error {
 	case DistributionSpecReferrersTagV1_1:
 		isApi := false
 		ds.ReferrersAPI = &isApi
-	case ReferrersAPIV1_1:
+	case DistributionSpecReferrersAPIV1_1:
 		isApi := true
 		ds.ReferrersAPI = &isApi
 	default:
@@ -102,7 +102,7 @@ func (ds *DistributionSpec) Set(value string) error {
 
 // Type returns the string value of the inner flag.
 func (ds *DistributionSpec) Type() string {
-	return strings.Join([]string{DistributionSpecReferrersTagV1_1, ReferrersAPIV1_1}, ",")
+	return strings.Join([]string{DistributionSpecReferrersTagV1_1, DistributionSpecReferrersAPIV1_1}, ",")
 }
 
 // String returns the string representation of the flag.

From 645e3adeed0b872e4a02f5abd9b1f0effe763f8f Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Thu, 28 Dec 2023 05:49:35 +0000
Subject: [PATCH 11/17] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/suite/command/attach.go   | 4 ++--
 test/e2e/suite/command/cp.go       | 4 ++--
 test/e2e/suite/command/discover.go | 2 +-
 test/e2e/suite/command/manifest.go | 4 ++--
 4 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/test/e2e/suite/command/attach.go b/test/e2e/suite/command/attach.go
index b83855653..341dac3b5 100644
--- a/test/e2e/suite/command/attach.go
+++ b/test/e2e/suite/command/attach.go
@@ -42,7 +42,7 @@ var _ = Describe("ORAS beginners:", func() {
 
 		It("should show preview and help doc", func() {
 			out := ORAS("attach", "--help").MatchKeyWords(feature.Preview.Mark+" Attach", feature.Preview.Description, ExampleDesc).Exec()
-			gomega.Expect(out).Should(gbytes.Say("--distribution-spec v1.1-referrers-tag, v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			gomega.Expect(out).Should(gbytes.Say("--distribution-spec v1.1-referrers-tag,v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 		})
 
 		It("should fail when no subject reference provided", func() {
@@ -81,7 +81,7 @@ var _ = Describe("ORAS beginners:", func() {
 			ORAS("attach", "--artifact-type", "test/attach", subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia), Flags.DistributionSpec, invalidFlag).
 				ExpectFailure().
 				WithWorkDir(PrepareTempFiles()).
-				MatchErrKeyWords("Error:", invalidFlag, "Available options: v1.1-referrers-tag, v1.1-referrers-api").
+				MatchErrKeyWords("Error:", invalidFlag, "Available options: v1.1-referrers-tag,v1.1-referrers-api").
 				Exec()
 		})
 	})
diff --git a/test/e2e/suite/command/cp.go b/test/e2e/suite/command/cp.go
index a6fc33fd9..8f5c08ded 100644
--- a/test/e2e/suite/command/cp.go
+++ b/test/e2e/suite/command/cp.go
@@ -43,9 +43,9 @@ var _ = Describe("ORAS beginners:", func() {
 	When("running cp command", func() {
 		It("should show help doc with feature flags", func() {
 			out := ORAS("cp", "--help").MatchKeyWords("Copy", ExampleDesc).Exec()
-			Expect(out).Should(gbytes.Say("--from-distribution-spec v1.1-referrers-tag, v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			Expect(out).Should(gbytes.Say("--from-distribution-spec v1.1-referrers-tag,v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 			Expect(out).Should(gbytes.Say("-r, --recursive\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
-			Expect(out).Should(gbytes.Say("--to-distribution-spec v1.1-referrers-tag, v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			Expect(out).Should(gbytes.Say("--to-distribution-spec v1.1-referrers-tag,v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 		})
 
 		It("should fail when no reference provided", func() {
diff --git a/test/e2e/suite/command/discover.go b/test/e2e/suite/command/discover.go
index 2989a07f5..26f26e99a 100644
--- a/test/e2e/suite/command/discover.go
+++ b/test/e2e/suite/command/discover.go
@@ -53,7 +53,7 @@ var _ = Describe("ORAS beginners:", func() {
 
 		It("should show preview and help doc", func() {
 			out := ORAS("discover", "--help").MatchKeyWords(feature.Preview.Mark+" Discover", feature.Preview.Description, ExampleDesc).Exec()
-			gomega.Expect(out).Should(gbytes.Say("--distribution-spec v1.1-referrers-tag, v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			gomega.Expect(out).Should(gbytes.Say("--distribution-spec v1.1-referrers-tag,v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 		})
 
 		It("should fail when no subject reference provided", func() {
diff --git a/test/e2e/suite/command/manifest.go b/test/e2e/suite/command/manifest.go
index 8e456e74e..c918adeeb 100644
--- a/test/e2e/suite/command/manifest.go
+++ b/test/e2e/suite/command/manifest.go
@@ -54,7 +54,7 @@ var _ = Describe("ORAS beginners:", func() {
 		When("running `manifest push`", func() {
 			It("should show help doc with feature flags", func() {
 				out := ORAS("manifest", "push", "--help").MatchKeyWords(ExampleDesc).Exec()
-				gomega.Expect(out).Should(gbytes.Say("--distribution-spec v1.1-referrers-tag, v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+				gomega.Expect(out).Should(gbytes.Say("--distribution-spec v1.1-referrers-tag,v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 			})
 
 			It("should have flag for prettifying JSON output", func() {
@@ -98,7 +98,7 @@ var _ = Describe("ORAS beginners:", func() {
 		When("running `manifest delete`", func() {
 			It("should show help doc with feature flags", func() {
 				out := ORAS("manifest", "delete", "--help").MatchKeyWords(ExampleDesc).Exec()
-				gomega.Expect(out).Should(gbytes.Say("--distribution-spec v1.1-referrers-tag, v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+				gomega.Expect(out).Should(gbytes.Say("--distribution-spec v1.1-referrers-tag,v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 			})
 
 			It("should fail and show detailed error description if no argument provided", func() {

From 2c1ca8270bf7d695ae84a3013f7ce567add3a891 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Thu, 28 Dec 2023 05:50:52 +0000
Subject: [PATCH 12/17] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/suite/command/push.go | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/test/e2e/suite/command/push.go b/test/e2e/suite/command/push.go
index 7338dd297..703fc3e90 100644
--- a/test/e2e/suite/command/push.go
+++ b/test/e2e/suite/command/push.go
@@ -38,7 +38,7 @@ var _ = Describe("ORAS beginners:", func() {
 	When("running push command", func() {
 		It("should show help description with feature flags", func() {
 			out := ORAS("push", "--help").MatchKeyWords(ExampleDesc).Exec().Out
-			gomega.Expect(out).Should(gbytes.Say("--image-spec v1.1, v1.0\\s+%s", regexp.QuoteMeta(feature.Experimental.Mark)))
+			gomega.Expect(out).Should(gbytes.Say("--image-spec v1.1,v1.0\\s+%s", regexp.QuoteMeta(feature.Experimental.Mark)))
 		})
 
 		It("should fail and show detailed error description if no argument provided", func() {
@@ -63,7 +63,7 @@ var _ = Describe("ORAS beginners:", func() {
 			invalidFlag := "???"
 			ORAS("push", subjectRef, Flags.ImageSpec, invalidFlag).
 				ExpectFailure().
-				MatchErrKeyWords("Error:", invalidFlag, "Available options: v1.1, v1.0").
+				MatchErrKeyWords("Error:", invalidFlag, "Available options: v1.1,v1.0").
 				Exec()
 		})
 	})

From 2e4c097481e356ebc8433086ed18f1f7d03ed9eb Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Thu, 28 Dec 2023 06:54:57 +0000
Subject: [PATCH 13/17] resolve comments

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/spec.go   | 28 ++++++++++++++++++++++------
 test/e2e/suite/command/attach.go   |  2 +-
 test/e2e/suite/command/cp.go       |  4 ++--
 test/e2e/suite/command/discover.go |  2 +-
 test/e2e/suite/command/manifest.go |  2 +-
 test/e2e/suite/command/push.go     | 22 +++++++++++++++++++++-
 6 files changed, 48 insertions(+), 12 deletions(-)

diff --git a/cmd/oras/internal/option/spec.go b/cmd/oras/internal/option/spec.go
index fcf4b8adb..c2d5f41a9 100644
--- a/cmd/oras/internal/option/spec.go
+++ b/cmd/oras/internal/option/spec.go
@@ -48,7 +48,7 @@ func (is *ImageSpec) Set(value string) error {
 	default:
 		return &oerrors.Error{
 			Err:            fmt.Errorf("unknown image specification flag: %s", value),
-			Recommendation: fmt.Sprintf("Available options: %s", is.Type()),
+			Recommendation: fmt.Sprintf("Available options: %s", strings.Join(is.Options(), ",")),
 		}
 	}
 	return nil
@@ -56,7 +56,15 @@ func (is *ImageSpec) Set(value string) error {
 
 // Type returns the string value of the inner flag.
 func (is *ImageSpec) Type() string {
-	return strings.Join([]string{ImageSpecV1_1, ImageSpecV1_0}, ",")
+	return "string"
+}
+
+// Options returns the usable options for the flag.
+func (is *ImageSpec) Options() []string {
+	return []string{
+		ImageSpecV1_1,
+		ImageSpecV1_0,
+	}
 }
 
 // String returns the string representation of the flag.
@@ -68,7 +76,7 @@ func (is *ImageSpec) String() string {
 func (is *ImageSpec) ApplyFlags(fs *pflag.FlagSet) {
 	// default to v1.1-rc.4
 	is.PackVersion = oras.PackManifestVersion1_1_RC4
-	fs.Var(is, "image-spec", `[Experimental] specify manifest type for building artifact (default "v1.1")`)
+	fs.Var(is, "image-spec", fmt.Sprintf(`[Experimental] specify manifest type for building artifact. Options: %s (default "v1.1")`, strings.Join(is.Options(), ",")))
 }
 
 // DistributionSpec option struct which implements pflag.Value interface.
@@ -94,7 +102,7 @@ func (ds *DistributionSpec) Set(value string) error {
 	default:
 		return &oerrors.Error{
 			Err:            fmt.Errorf("unknown distribution specification flag: %s", value),
-			Recommendation: fmt.Sprintf("Available options: %s", ds.Type()),
+			Recommendation: fmt.Sprintf("Available options: %s", strings.Join(ds.Options(), ",")),
 		}
 	}
 	return nil
@@ -102,7 +110,15 @@ func (ds *DistributionSpec) Set(value string) error {
 
 // Type returns the string value of the inner flag.
 func (ds *DistributionSpec) Type() string {
-	return strings.Join([]string{DistributionSpecReferrersTagV1_1, DistributionSpecReferrersAPIV1_1}, ",")
+	return "string"
+}
+
+// Options returns the usable options for the flag.
+func (ds *DistributionSpec) Options() []string {
+	return []string{
+		DistributionSpecReferrersTagV1_1,
+		DistributionSpecReferrersAPIV1_1,
+	}
 }
 
 // String returns the string representation of the flag.
@@ -113,5 +129,5 @@ func (ds *DistributionSpec) String() string {
 // ApplyFlagsWithPrefix applies flags to a command flag set with a prefix string.
 func (ds *DistributionSpec) ApplyFlagsWithPrefix(fs *pflag.FlagSet, prefix, description string) {
 	flagPrefix, notePrefix := applyPrefix(prefix, description)
-	fs.Var(ds, flagPrefix+"distribution-spec", "[Preview] set OCI distribution spec version and API option for "+notePrefix+"target.")
+	fs.Var(ds, flagPrefix+"distribution-spec", fmt.Sprintf("[Preview] set OCI distribution spec version and API option for "+notePrefix+"target. Options: ", strings.Join(ds.Options(), ",")))
 }
diff --git a/test/e2e/suite/command/attach.go b/test/e2e/suite/command/attach.go
index 341dac3b5..1b3980ea9 100644
--- a/test/e2e/suite/command/attach.go
+++ b/test/e2e/suite/command/attach.go
@@ -42,7 +42,7 @@ var _ = Describe("ORAS beginners:", func() {
 
 		It("should show preview and help doc", func() {
 			out := ORAS("attach", "--help").MatchKeyWords(feature.Preview.Mark+" Attach", feature.Preview.Description, ExampleDesc).Exec()
-			gomega.Expect(out).Should(gbytes.Say("--distribution-spec v1.1-referrers-tag,v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			gomega.Expect(out).Should(gbytes.Say("--distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 		})
 
 		It("should fail when no subject reference provided", func() {
diff --git a/test/e2e/suite/command/cp.go b/test/e2e/suite/command/cp.go
index 8f5c08ded..45718fa29 100644
--- a/test/e2e/suite/command/cp.go
+++ b/test/e2e/suite/command/cp.go
@@ -43,9 +43,9 @@ var _ = Describe("ORAS beginners:", func() {
 	When("running cp command", func() {
 		It("should show help doc with feature flags", func() {
 			out := ORAS("cp", "--help").MatchKeyWords("Copy", ExampleDesc).Exec()
-			Expect(out).Should(gbytes.Say("--from-distribution-spec v1.1-referrers-tag,v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			Expect(out).Should(gbytes.Say("--from-distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 			Expect(out).Should(gbytes.Say("-r, --recursive\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
-			Expect(out).Should(gbytes.Say("--to-distribution-spec v1.1-referrers-tag,v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			Expect(out).Should(gbytes.Say("--to-distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 		})
 
 		It("should fail when no reference provided", func() {
diff --git a/test/e2e/suite/command/discover.go b/test/e2e/suite/command/discover.go
index 26f26e99a..fd2f678f5 100644
--- a/test/e2e/suite/command/discover.go
+++ b/test/e2e/suite/command/discover.go
@@ -53,7 +53,7 @@ var _ = Describe("ORAS beginners:", func() {
 
 		It("should show preview and help doc", func() {
 			out := ORAS("discover", "--help").MatchKeyWords(feature.Preview.Mark+" Discover", feature.Preview.Description, ExampleDesc).Exec()
-			gomega.Expect(out).Should(gbytes.Say("--distribution-spec v1.1-referrers-tag,v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			gomega.Expect(out).Should(gbytes.Say("--distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 		})
 
 		It("should fail when no subject reference provided", func() {
diff --git a/test/e2e/suite/command/manifest.go b/test/e2e/suite/command/manifest.go
index c918adeeb..2801b8079 100644
--- a/test/e2e/suite/command/manifest.go
+++ b/test/e2e/suite/command/manifest.go
@@ -54,7 +54,7 @@ var _ = Describe("ORAS beginners:", func() {
 		When("running `manifest push`", func() {
 			It("should show help doc with feature flags", func() {
 				out := ORAS("manifest", "push", "--help").MatchKeyWords(ExampleDesc).Exec()
-				gomega.Expect(out).Should(gbytes.Say("--distribution-spec v1.1-referrers-tag,v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+				gomega.Expect(out).Should(gbytes.Say("--distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 			})
 
 			It("should have flag for prettifying JSON output", func() {
diff --git a/test/e2e/suite/command/push.go b/test/e2e/suite/command/push.go
index 703fc3e90..5a6f03eb1 100644
--- a/test/e2e/suite/command/push.go
+++ b/test/e2e/suite/command/push.go
@@ -38,7 +38,7 @@ var _ = Describe("ORAS beginners:", func() {
 	When("running push command", func() {
 		It("should show help description with feature flags", func() {
 			out := ORAS("push", "--help").MatchKeyWords(ExampleDesc).Exec().Out
-			gomega.Expect(out).Should(gbytes.Say("--image-spec v1.1,v1.0\\s+%s", regexp.QuoteMeta(feature.Experimental.Mark)))
+			gomega.Expect(out).Should(gbytes.Say("--image-spec string\\s+%s", regexp.QuoteMeta(feature.Experimental.Mark)))
 		})
 
 		It("should fail and show detailed error description if no argument provided", func() {
@@ -66,6 +66,26 @@ var _ = Describe("ORAS beginners:", func() {
 				MatchErrKeyWords("Error:", invalidFlag, "Available options: v1.1,v1.0").
 				Exec()
 		})
+
+		It("should fail if image spec is not valid", func() {
+			testRepo := attachTestRepo("invalid-image-spec")
+			subjectRef := RegistryRef(ZOTHost, testRepo, foobar.Tag)
+			invalidFlag := "???"
+			ORAS("push", subjectRef, Flags.ImageSpec, invalidFlag).
+				ExpectFailure().
+				MatchErrKeyWords("Error:", invalidFlag, "Available options: v1.1,v1.0").
+				Exec()
+		})
+
+		It("should fail if image spec is not valid", func() {
+			testRepo := attachTestRepo("invalid-image-spec")
+			subjectRef := RegistryRef(ZOTHost, testRepo, foobar.Tag)
+			invalidFlag := "???"
+			ORAS("push", subjectRef, Flags.ImageSpec, invalidFlag).
+				ExpectFailure().
+				MatchErrKeyWords("Error:", invalidFlag, "Available options: v1.1,v1.0").
+				Exec()
+		})
 	})
 })
 

From db738ccf44d967f654820a972af2b1e649ac4395 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Thu, 28 Dec 2023 06:58:20 +0000
Subject: [PATCH 14/17] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/suite/command/manifest.go | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/e2e/suite/command/manifest.go b/test/e2e/suite/command/manifest.go
index 2801b8079..6f7c10ebc 100644
--- a/test/e2e/suite/command/manifest.go
+++ b/test/e2e/suite/command/manifest.go
@@ -98,7 +98,7 @@ var _ = Describe("ORAS beginners:", func() {
 		When("running `manifest delete`", func() {
 			It("should show help doc with feature flags", func() {
 				out := ORAS("manifest", "delete", "--help").MatchKeyWords(ExampleDesc).Exec()
-				gomega.Expect(out).Should(gbytes.Say("--distribution-spec v1.1-referrers-tag,v1.1-referrers-api\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+				gomega.Expect(out).Should(gbytes.Say("--distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 			})
 
 			It("should fail and show detailed error description if no argument provided", func() {

From 8dd85148b27058006c6d8c94c1d91de92c8a43db Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Fri, 29 Dec 2023 06:35:22 +0000
Subject: [PATCH 15/17] resolve comments

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/spec.go | 32 ++++++++++++++++++--------------
 test/e2e/suite/command/attach.go |  2 +-
 test/e2e/suite/command/push.go   |  6 +++---
 3 files changed, 22 insertions(+), 18 deletions(-)

diff --git a/cmd/oras/internal/option/spec.go b/cmd/oras/internal/option/spec.go
index c2d5f41a9..4a51a820d 100644
--- a/cmd/oras/internal/option/spec.go
+++ b/cmd/oras/internal/option/spec.go
@@ -25,8 +25,11 @@ import (
 )
 
 const (
-	ImageSpecV1_1                    = "v1.1"
-	ImageSpecV1_0                    = "v1.0"
+	ImageSpecV1_1 = "v1.1"
+	ImageSpecV1_0 = "v1.0"
+)
+
+const (
 	DistributionSpecReferrersTagV1_1 = "v1.1-referrers-tag"
 	DistributionSpecReferrersAPIV1_1 = "v1.1-referrers-api"
 )
@@ -48,7 +51,7 @@ func (is *ImageSpec) Set(value string) error {
 	default:
 		return &oerrors.Error{
 			Err:            fmt.Errorf("unknown image specification flag: %s", value),
-			Recommendation: fmt.Sprintf("Available options: %s", strings.Join(is.Options(), ",")),
+			Recommendation: fmt.Sprintf("Available options: %s", is.Options()),
 		}
 	}
 	return nil
@@ -59,12 +62,12 @@ func (is *ImageSpec) Type() string {
 	return "string"
 }
 
-// Options returns the usable options for the flag.
-func (is *ImageSpec) Options() []string {
-	return []string{
+// Options returns the string of usable options for the flag.
+func (is *ImageSpec) Options() string {
+	return strings.Join([]string{
 		ImageSpecV1_1,
 		ImageSpecV1_0,
-	}
+	}, ", ")
 }
 
 // String returns the string representation of the flag.
@@ -76,7 +79,8 @@ func (is *ImageSpec) String() string {
 func (is *ImageSpec) ApplyFlags(fs *pflag.FlagSet) {
 	// default to v1.1-rc.4
 	is.PackVersion = oras.PackManifestVersion1_1_RC4
-	fs.Var(is, "image-spec", fmt.Sprintf(`[Experimental] specify manifest type for building artifact. Options: %s (default "v1.1")`, strings.Join(is.Options(), ",")))
+	defaultFlag := ImageSpecV1_1
+	fs.Var(is, "image-spec", fmt.Sprintf(`[Experimental] specify manifest type for building artifact. Options: %s (default %q)`, is.Options(), defaultFlag))
 }
 
 // DistributionSpec option struct which implements pflag.Value interface.
@@ -102,7 +106,7 @@ func (ds *DistributionSpec) Set(value string) error {
 	default:
 		return &oerrors.Error{
 			Err:            fmt.Errorf("unknown distribution specification flag: %s", value),
-			Recommendation: fmt.Sprintf("Available options: %s", strings.Join(ds.Options(), ",")),
+			Recommendation: fmt.Sprintf("Available options: %s", ds.Options()),
 		}
 	}
 	return nil
@@ -113,12 +117,12 @@ func (ds *DistributionSpec) Type() string {
 	return "string"
 }
 
-// Options returns the usable options for the flag.
-func (ds *DistributionSpec) Options() []string {
-	return []string{
+// Options returns the string of usable options for the flag.
+func (ds *DistributionSpec) Options() string {
+	return strings.Join([]string{
 		DistributionSpecReferrersTagV1_1,
 		DistributionSpecReferrersAPIV1_1,
-	}
+	}, ", ")
 }
 
 // String returns the string representation of the flag.
@@ -129,5 +133,5 @@ func (ds *DistributionSpec) String() string {
 // ApplyFlagsWithPrefix applies flags to a command flag set with a prefix string.
 func (ds *DistributionSpec) ApplyFlagsWithPrefix(fs *pflag.FlagSet, prefix, description string) {
 	flagPrefix, notePrefix := applyPrefix(prefix, description)
-	fs.Var(ds, flagPrefix+"distribution-spec", fmt.Sprintf("[Preview] set OCI distribution spec version and API option for "+notePrefix+"target. Options: ", strings.Join(ds.Options(), ",")))
+	fs.Var(ds, flagPrefix+"distribution-spec", fmt.Sprintf("[Preview] set OCI distribution spec version and API option for "+notePrefix+"target. Options: ", ds.Options()))
 }
diff --git a/test/e2e/suite/command/attach.go b/test/e2e/suite/command/attach.go
index 1b3980ea9..269337b04 100644
--- a/test/e2e/suite/command/attach.go
+++ b/test/e2e/suite/command/attach.go
@@ -81,7 +81,7 @@ var _ = Describe("ORAS beginners:", func() {
 			ORAS("attach", "--artifact-type", "test/attach", subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia), Flags.DistributionSpec, invalidFlag).
 				ExpectFailure().
 				WithWorkDir(PrepareTempFiles()).
-				MatchErrKeyWords("Error:", invalidFlag, "Available options: v1.1-referrers-tag,v1.1-referrers-api").
+				MatchErrKeyWords("Error:", invalidFlag, "Available options: v1.1-referrers-tag, v1.1-referrers-api").
 				Exec()
 		})
 	})
diff --git a/test/e2e/suite/command/push.go b/test/e2e/suite/command/push.go
index 5a6f03eb1..8cc8fcbcf 100644
--- a/test/e2e/suite/command/push.go
+++ b/test/e2e/suite/command/push.go
@@ -63,7 +63,7 @@ var _ = Describe("ORAS beginners:", func() {
 			invalidFlag := "???"
 			ORAS("push", subjectRef, Flags.ImageSpec, invalidFlag).
 				ExpectFailure().
-				MatchErrKeyWords("Error:", invalidFlag, "Available options: v1.1,v1.0").
+				MatchErrKeyWords("Error:", invalidFlag, "Available options: v1.1, v1.0").
 				Exec()
 		})
 
@@ -73,7 +73,7 @@ var _ = Describe("ORAS beginners:", func() {
 			invalidFlag := "???"
 			ORAS("push", subjectRef, Flags.ImageSpec, invalidFlag).
 				ExpectFailure().
-				MatchErrKeyWords("Error:", invalidFlag, "Available options: v1.1,v1.0").
+				MatchErrKeyWords("Error:", invalidFlag, "Available options: v1.1, v1.0").
 				Exec()
 		})
 
@@ -83,7 +83,7 @@ var _ = Describe("ORAS beginners:", func() {
 			invalidFlag := "???"
 			ORAS("push", subjectRef, Flags.ImageSpec, invalidFlag).
 				ExpectFailure().
-				MatchErrKeyWords("Error:", invalidFlag, "Available options: v1.1,v1.0").
+				MatchErrKeyWords("Error:", invalidFlag, "Available options: v1.1, v1.0").
 				Exec()
 		})
 	})

From b6341e9b6c8e5991a23a7e7df79e1cc737eea4f0 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Fri, 29 Dec 2023 06:44:22 +0000
Subject: [PATCH 16/17] increase coverage

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/suite/command/push.go | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/test/e2e/suite/command/push.go b/test/e2e/suite/command/push.go
index 8cc8fcbcf..a12d42518 100644
--- a/test/e2e/suite/command/push.go
+++ b/test/e2e/suite/command/push.go
@@ -300,7 +300,7 @@ var _ = Describe("Remote registry users:", func() {
 			Expect(manifest.Annotations[annotationKey]).Should(Equal(annotationValue))
 		})
 
-		It("should push artifact with blob", func() {
+		It("should push files", func() {
 			repo := pushTestRepo("artifact-with-blob")
 			tempDir := PrepareTempFiles()
 
@@ -312,7 +312,24 @@ var _ = Describe("Remote registry users:", func() {
 			fetched := ORAS("manifest", "fetch", RegistryRef(ZOTHost, repo, tag)).Exec().Out.Contents()
 			var manifest ocispec.Manifest
 			Expect(json.Unmarshal(fetched, &manifest)).ShouldNot(HaveOccurred())
-			Expect(manifest.ArtifactType).Should(Equal(artifact.DefaultArtifactType))
+			Expect(manifest.ArtifactType).Should(Equal("application/vnd.unknown.artifact.v1"))
+			Expect(manifest.Layers).Should(ContainElements(foobar.BlobBarDescriptor("application/vnd.oci.image.layer.v1.tar")))
+			Expect(manifest.Config).Should(Equal(artifact.EmptyLayerJSON))
+		})
+
+		It("should push v1.1-rc.4 artifact", func() {
+			repo := pushTestRepo("artifact-with-blob")
+			tempDir := PrepareTempFiles()
+
+			ORAS("push", RegistryRef(ZOTHost, repo, tag), foobar.FileBarName, "-v", "--image-spec", "v1.1").
+				MatchStatus([]match.StateKey{foobar.FileBarStateKey, artifact.DefaultConfigStateKey}, true, 2).
+				WithWorkDir(tempDir).Exec()
+
+			// validate
+			fetched := ORAS("manifest", "fetch", RegistryRef(ZOTHost, repo, tag)).Exec().Out.Contents()
+			var manifest ocispec.Manifest
+			Expect(json.Unmarshal(fetched, &manifest)).ShouldNot(HaveOccurred())
+			Expect(manifest.ArtifactType).Should(Equal("application/vnd.unknown.artifact.v1"))
 			Expect(manifest.Layers).Should(ContainElements(foobar.BlobBarDescriptor("application/vnd.oci.image.layer.v1.tar")))
 			Expect(manifest.Config).Should(Equal(artifact.EmptyLayerJSON))
 		})

From c12f05c13cfd6c01828fbbfe62909d664ac27c7e Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Fri, 29 Dec 2023 06:55:10 +0000
Subject: [PATCH 17/17] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/suite/command/push.go | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/e2e/suite/command/push.go b/test/e2e/suite/command/push.go
index a12d42518..1126c4c81 100644
--- a/test/e2e/suite/command/push.go
+++ b/test/e2e/suite/command/push.go
@@ -318,7 +318,7 @@ var _ = Describe("Remote registry users:", func() {
 		})
 
 		It("should push v1.1-rc.4 artifact", func() {
-			repo := pushTestRepo("artifact-with-blob")
+			repo := pushTestRepo("v1.1-artifact")
 			tempDir := PrepareTempFiles()
 
 			ORAS("push", RegistryRef(ZOTHost, repo, tag), foobar.FileBarName, "-v", "--image-spec", "v1.1").