feat: add package versions list command

Add list support for alternative distribution package versions and update
README examples and CLI validation tests.

Author: rudrankriyam

README.md

@@ -402,6 +402,7 @@ asc alternative-distribution keys app --app "APP_ID"
 # Create and fetch packages and versions
 asc alternative-distribution packages create --app-store-version-id "APP_STORE_VERSION_ID"
 asc alternative-distribution packages get --package-id "PACKAGE_ID"
+asc alternative-distribution packages versions list --package-id "PACKAGE_ID"
 asc alternative-distribution packages versions get --version-id "VERSION_ID"
 asc alternative-distribution packages versions deltas --version-id "VERSION_ID"
 asc alternative-distribution packages versions variants --version-id "VERSION_ID"

internal/cli/alternativedistribution/alternative_distribution_package_versions.go

@@ -23,12 +23,14 @@ func AlternativeDistributionPackageVersionsCommand() *ffcli.Command {
 		LongHelp: `Manage alternative distribution package versions.
 
 Examples:
+  asc alternative-distribution packages versions list --package-id "PACKAGE_ID"
   asc alternative-distribution packages versions get --version-id "VERSION_ID"
   asc alternative-distribution packages versions deltas --version-id "VERSION_ID"
   asc alternative-distribution packages versions variants --version-id "VERSION_ID"`,
 		FlagSet:   fs,
 		UsageFunc: DefaultUsageFunc,
 		Subcommands: []*ffcli.Command{
+			AlternativeDistributionPackageVersionsListCommand(),
 			AlternativeDistributionPackageVersionsGetCommand(),
 			AlternativeDistributionPackageVersionsDeltasCommand(),
 			AlternativeDistributionPackageVersionsVariantsCommand(),
@@ -39,6 +41,81 @@ Examples:
 	}
 }
 
+// AlternativeDistributionPackageVersionsListCommand returns the package versions list subcommand.
+func AlternativeDistributionPackageVersionsListCommand() *ffcli.Command {
+	fs := flag.NewFlagSet("list", flag.ExitOnError)
+
+	packageID := fs.String("package-id", "", "Alternative distribution package ID")
+	limit := fs.Int("limit", 0, "Maximum results per page (1-200)")
+	next := fs.String("next", "", "Fetch next page using a links.next URL")
+	paginate := fs.Bool("paginate", false, "Automatically fetch all pages (aggregate results)")
+	output := fs.String("output", "json", "Output format: json (default), table, markdown")
+	pretty := fs.Bool("pretty", false, "Pretty-print JSON output")
+
+	return &ffcli.Command{
+		Name:       "list",
+		ShortUsage: "asc alternative-distribution packages versions list --package-id \"PACKAGE_ID\" [flags]",
+		ShortHelp:  "List alternative distribution package versions.",
+		LongHelp: `List alternative distribution package versions.
+
+Examples:
+  asc alternative-distribution packages versions list --package-id "PACKAGE_ID"
+  asc alternative-distribution packages versions list --package-id "PACKAGE_ID" --paginate`,
+		FlagSet:   fs,
+		UsageFunc: DefaultUsageFunc,
+		Exec: func(ctx context.Context, args []string) error {
+			trimmedID := strings.TrimSpace(*packageID)
+			if trimmedID == "" {
+				fmt.Fprintln(os.Stderr, "Error: --package-id is required")
+				return flag.ErrHelp
+			}
+			if *limit != 0 && (*limit < 1 || *limit > alternativeDistributionMaxLimit) {
+				return fmt.Errorf("alternative-distribution packages versions list: --limit must be between 1 and %d", alternativeDistributionMaxLimit)
+			}
+			if err := validateNextURL(*next); err != nil {
+				return fmt.Errorf("alternative-distribution packages versions list: %w", err)
+			}
+
+			client, err := getASCClient()
+			if err != nil {
+				return fmt.Errorf("alternative-distribution packages versions list: %w", err)
+			}
+
+			requestCtx, cancel := contextWithTimeout(ctx)
+			defer cancel()
+
+			opts := []asc.AlternativeDistributionPackageVersionsOption{
+				asc.WithAlternativeDistributionPackageVersionsLimit(*limit),
+				asc.WithAlternativeDistributionPackageVersionsNextURL(*next),
+			}
+
+			if *paginate {
+				paginateOpts := append(opts, asc.WithAlternativeDistributionPackageVersionsLimit(alternativeDistributionMaxLimit))
+				firstPage, err := client.GetAlternativeDistributionPackageVersions(requestCtx, trimmedID, paginateOpts...)
+				if err != nil {
+					return fmt.Errorf("alternative-distribution packages versions list: failed to fetch: %w", err)
+				}
+
+				resp, err := asc.PaginateAll(requestCtx, firstPage, func(ctx context.Context, nextURL string) (asc.PaginatedResponse, error) {
+					return client.GetAlternativeDistributionPackageVersions(ctx, trimmedID, asc.WithAlternativeDistributionPackageVersionsNextURL(nextURL))
+				})
+				if err != nil {
+					return fmt.Errorf("alternative-distribution packages versions list: %w", err)
+				}
+
+				return printOutput(resp, *output, *pretty)
+			}
+
+			resp, err := client.GetAlternativeDistributionPackageVersions(requestCtx, trimmedID, opts...)
+			if err != nil {
+				return fmt.Errorf("alternative-distribution packages versions list: failed to fetch: %w", err)
+			}
+
+			return printOutput(resp, *output, *pretty)
+		},
+	}
+}
+
 // AlternativeDistributionPackageVersionsGetCommand returns the package versions get subcommand.
 func AlternativeDistributionPackageVersionsGetCommand() *ffcli.Command {
 	fs := flag.NewFlagSet("get", flag.ExitOnError)

internal/cli/alternativedistribution/alternative_distribution_packages.go

@@ -24,6 +24,7 @@ Examples:
   asc alternative-distribution packages get --package-id "PACKAGE_ID"
   asc alternative-distribution packages create --app-store-version-id "APP_STORE_VERSION_ID"
   asc alternative-distribution packages app-store-version --app-store-version-id "APP_STORE_VERSION_ID"
+  asc alternative-distribution packages versions list --package-id "PACKAGE_ID"
   asc alternative-distribution packages versions get --version-id "VERSION_ID"
   asc alternative-distribution packages versions deltas --version-id "VERSION_ID"
   asc alternative-distribution packages versions variants --version-id "VERSION_ID"

internal/cli/alternativedistribution/alternative_distribution_test.go

@@ -219,6 +219,17 @@ func TestAlternativeDistributionPackageVersionsGetCommand_MissingID(t *testing.T
 	}
 }
 
+func TestAlternativeDistributionPackageVersionsListCommand_MissingID(t *testing.T) {
+	cmd := AlternativeDistributionPackageVersionsListCommand()
+	if err := cmd.FlagSet.Parse([]string{}); err != nil {
+		t.Fatalf("failed to parse flags: %v", err)
+	}
+
+	if err := cmd.Exec(context.Background(), []string{}); err != flag.ErrHelp {
+		t.Fatalf("expected flag.ErrHelp when --package-id is missing, got %v", err)
+	}
+}
+
 func TestAlternativeDistributionPackageVersionsDeltasCommand_MissingID(t *testing.T) {
 	cmd := AlternativeDistributionPackageVersionsDeltasCommand()
 	if err := cmd.FlagSet.Parse([]string{}); err != nil {
@@ -251,3 +262,14 @@ func TestAlternativeDistributionPackageVersionsDeltasCommand_InvalidLimit(t *tes
 		t.Fatalf("expected validation error for invalid --limit, got %v", err)
 	}
 }
+
+func TestAlternativeDistributionPackageVersionsListCommand_InvalidLimit(t *testing.T) {
+	cmd := AlternativeDistributionPackageVersionsListCommand()
+	if err := cmd.FlagSet.Parse([]string{"--package-id", "PACKAGE_ID", "--limit", "1000"}); err != nil {
+		t.Fatalf("failed to parse flags: %v", err)
+	}
+
+	if err := cmd.Exec(context.Background(), []string{}); err == nil || err == flag.ErrHelp {
+		t.Fatalf("expected validation error for invalid --limit, got %v", err)
+	}
+}