Merge pull request #39 from alpacax/copilot/fix-38

Enhance CLI error messages with clear, actionable guidance

Author: eunyoung14

api/ftp/ftp.go

@@ -255,7 +255,7 @@ func DownloadFile(ac *client.AlpaconClient, src, dest, username, groupname strin
 		for count := 0; count < maxAttempts; count++ {
 			resp, err = http.Get(downloadResponse.DownloadURL)
 			if err != nil {
-				return err
+				return fmt.Errorf("network error while downloading: %w", err)
 			}
 
 			if resp.StatusCode == http.StatusOK {
@@ -273,7 +273,7 @@ func DownloadFile(ac *client.AlpaconClient, src, dest, username, groupname strin
 
 		respBody, err := io.ReadAll(resp.Body)
 		if err != nil {
-			return err
+			return fmt.Errorf("failed to read download response: %w", err)
 		}
 
 		var fileName string
@@ -284,16 +284,16 @@ func DownloadFile(ac *client.AlpaconClient, src, dest, username, groupname strin
 		}
 		err = utils.SaveFile(filepath.Join(dest, fileName), respBody)
 		if err != nil {
-			return err
+			return fmt.Errorf("failed to save file locally: %w", err)
 		}
 		if recursive {
 			err = utils.Unzip(filepath.Join(dest, fileName), dest)
 			if err != nil {
-				return err
+				return fmt.Errorf("failed to extract downloaded folder: %w", err)
 			}
 			err = utils.DeleteFile(filepath.Join(dest, fileName))
 			if err != nil {
-				return err
+				return fmt.Errorf("failed to clean up temporary zip file: %w", err)
 			}
 		}
 	}

client/client.go

@@ -26,7 +26,7 @@ const (
 func NewAlpaconAPIClient() (*AlpaconClient, error) {
 	validConfig, err := config.LoadConfig()
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("configuration file not found or invalid: %v. Please run 'alpacon login' to configure your connection", err)
 	}
 
 	httpClient := &http.Client{
@@ -49,7 +49,7 @@ func NewAlpaconAPIClient() (*AlpaconClient, error) {
 		fmt.Println("Refreshing access token...")
 		tokenRes, err := auth0.RefreshAccessToken(validConfig.WorkspaceURL, httpClient, validConfig.RefreshToken)
 		if err != nil {
-			return nil, fmt.Errorf("failed to refresh access token: %v", err)
+			return nil, fmt.Errorf("failed to refresh access token: %v. Your session may have expired completely. Please run 'alpacon login' to authenticate again", err)
 		}
 
 		client.AccessToken = tokenRes.AccessToken
@@ -81,7 +81,7 @@ func (ac *AlpaconClient) checkAuth() error {
 		return err
 	}
 	if !checkAuthResponse.Authenticated {
-		return errors.New("authenticated failed")
+		return errors.New("authentication failed: your login session has expired or is invalid. Please run 'alpacon login' to authenticate again")
 	}
 
 	return nil

cmd/agent/agent.go

@@ -13,7 +13,7 @@ var AgentCmd = &cobra.Command{
 		if err != nil {
 			return err
 		}
-		return errors.New("subcommand error")
+		return errors.New("a subcommand is required. Use 'alpacon agent upgrade', 'alpacon agent restart', or 'alpacon agent shutdown' to manage the server agent. Run 'alpacon agent --help' for more information")
 	},
 }
 

cmd/authority/authority.go

@@ -13,7 +13,7 @@ var AuthorityCmd = &cobra.Command{
 		if err != nil {
 			return err
 		}
-		return errors.New("subcommand error")
+		return errors.New("a subcommand is required. Use 'alpacon authority create', 'alpacon authority list', 'alpacon authority detail', 'alpacon authority download', or 'alpacon authority delete'. Run 'alpacon authority --help' for more information")
 	},
 }
 

cmd/cert/cert.go

@@ -14,7 +14,7 @@ var CertCmd = &cobra.Command{
 		if err != nil {
 			return err
 		}
-		return errors.New("subcommand error")
+		return errors.New("a subcommand is required. Use 'alpacon cert list', 'alpacon cert detail', or 'alpacon cert download' to manage SSL/TLS certificates. Run 'alpacon cert --help' for more information")
 	},
 }
 

cmd/csr/csr.go

@@ -13,7 +13,7 @@ var CsrCmd = &cobra.Command{
 		if err != nil {
 			return err
 		}
-		return errors.New("subcommand error")
+		return errors.New("a subcommand is required. Use 'alpacon csr create', 'alpacon csr list', 'alpacon csr approve', 'alpacon csr deny', 'alpacon csr delete', or 'alpacon csr detail'. Run 'alpacon csr --help' for more information")
 	},
 }
 

cmd/ftp/cp.go

@@ -3,6 +3,7 @@ package ftp
 import (
 	"fmt"
 	"github.com/alpacax/alpacon-cli/api/mfa"
+	"path/filepath"
 	"strings"
 	"time"
 
@@ -44,7 +45,15 @@ var CpCmd = &cobra.Command{
 		recursive, _ := cmd.Flags().GetBool("recursive")
 
 		if len(args) < 2 {
-			utils.CliError("You must specify at least two arguments.")
+			utils.CliError("You must specify at least two arguments.\n\n" +
+				"Usage examples:\n" +
+				"  • Upload file to server:\n" +
+				"    alpacon cp /local/file.txt server:/remote/path/\n" +
+				"  • Download file from server:\n" +
+				"    alpacon cp server:/remote/file.txt /local/path/\n" +
+				"  • Upload folder (recursive):\n" +
+				"    alpacon cp -r /local/folder server:/remote/path/\n\n" +
+				"Note: Remote paths must include server name (e.g., myserver:/path/)")
 			return
 		}
 
@@ -67,9 +76,19 @@ var CpCmd = &cobra.Command{
 		sources := args[:len(args)-1]
 		dest := args[len(args)-1]
 
+		// Validate source and destination paths
+		if err := validatePaths(sources, dest); err != nil {
+			utils.CliError("%s", err.Error())
+			return
+		}
+
 		alpaconClient, err := client.NewAlpaconAPIClient()
 		if err != nil {
-			utils.CliError("Connection to Alpacon API failed: %s. Consider re-logging.", err)
+			utils.CliError("Connection to Alpacon API failed: %s.\n\n"+
+				"Try these solutions:\n"+
+				"  • Re-login with 'alpacon login'\n"+
+				"  • Check your internet connection\n"+
+				"  • Verify the API endpoint is accessible", err)
 			return
 		}
 
@@ -94,7 +113,8 @@ var CpCmd = &cobra.Command{
 						}
 					}
 				} else {
-					utils.CliError("Failed to upload the file to server: %s.", err)
+					// Error already handled in uploadObject
+					return
 				}
 			}
 		} else if isRemotePath(sources[0]) && isLocalPath(dest) {
@@ -118,11 +138,16 @@ var CpCmd = &cobra.Command{
 						}
 					}
 				} else {
-					utils.CliError("Failed to download the file from server: %s.", err)
+					// Error already handled in downloadObject
+					return
 				}
 			}
 		} else {
-			utils.CliError("Invalid combination of source and destination paths.")
+			utils.CliError("Invalid combination of source and destination paths.\n\n" +
+				"Valid operations:\n" +
+				"  • Upload (local → remote): alpacon cp /local/file server:/remote/path/\n" +
+				"  • Download (remote → local): alpacon cp server:/remote/file /local/path/\n\n" +
+				"Note: Remote paths must be in format 'servername:/path' (e.g., myserver:/tmp/file.txt)")
 		}
 	},
 }
@@ -154,16 +179,97 @@ func isLocalPaths(paths []string) bool {
 	return true
 }
 
+func validatePaths(sources []string, dest string) error {
+	// Check for mixed local and remote sources (not allowed)
+	hasLocal := false
+	hasRemote := false
+
+	for _, src := range sources {
+		if isRemotePath(src) {
+			hasRemote = true
+		} else {
+			hasLocal = true
+		}
+	}
+
+	if hasLocal && hasRemote {
+		return fmt.Errorf("cannot mix local and remote source paths in a single operation.\n\n" +
+			"Examples of valid operations:\n" +
+			"  • Upload multiple local files: alpacon cp file1.txt file2.txt server:/remote/\n" +
+			"  • Download single remote file: alpacon cp server:/remote/file.txt /local/\n" +
+			"  • Cannot mix: alpacon cp file1.txt server:/file2.txt /dest/  ❌")
+	}
+
+	// Check for invalid remote path format
+	allPaths := append(sources, dest)
+	for _, path := range allPaths {
+		if isRemotePath(path) {
+			if !strings.Contains(path, ":") {
+				return fmt.Errorf("invalid remote path format: '%s'\n\n"+
+					"Remote paths must be in format 'servername:/path'\n"+
+					"Examples:\n"+
+					"  • myserver:/home/user/file.txt\n"+
+					"  • web-server:/var/www/index.html", path)
+			}
+
+			parts := strings.SplitN(path, ":", 2)
+			if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
+				return fmt.Errorf("invalid remote path format: '%s'\n\n"+
+					"Remote paths must include both server name and path:\n"+
+					"  • Correct: myserver:/path/to/file\n"+
+					"  • Incorrect: :myfile (missing server name)\n"+
+					"  • Incorrect: myserver: (missing path)", path)
+			}
+		}
+	}
+
+	return nil
+}
+
 func uploadObject(client *client.AlpaconClient, src []string, dest, username, groupname string, recursive bool) error {
 	var result []string
 	var err error
 
+	// Extract server name for better error messages
+	serverName, remotePath := utils.SplitPath(dest)
+
 	if recursive {
 		result, err = ftp.UploadFolder(client, src, dest, username, groupname)
 	} else {
 		result, err = ftp.UploadFile(client, src, dest, username, groupname)
 	}
 	if err != nil {
+		// Parse error and provide specific guidance
+		errStr := err.Error()
+		if strings.Contains(errStr, "no such file or directory") {
+			utils.CliError("Source file(s) not found: %s\n\n"+
+				"Please check:\n"+
+				"  • File paths are correct and files exist\n"+
+				"  • You have read permissions for the source files\n"+
+				"  • For folders, use -r flag: alpacon cp -r /local/folder %s",
+				strings.Join(src, ", "), dest)
+		} else if strings.Contains(errStr, "permission denied") || strings.Contains(errStr, "access denied") {
+			utils.CliError("Permission denied uploading to '%s' on server '%s'.\n\n"+
+				"Try these solutions:\n"+
+				"  • Upload as root: alpacon cp -u root %s %s\n"+
+				"  • Upload to writable location: alpacon cp %s %s:/tmp/\n"+
+				"  • Check destination directory permissions\n"+
+				"  • Ensure destination directory exists",
+				remotePath, serverName, strings.Join(src, " "), dest, strings.Join(src, " "), serverName)
+		} else if strings.Contains(errStr, "server not found") || strings.Contains(errStr, "unknown host") {
+			utils.CliError("Server '%s' not found.\n\n"+
+				"Please check:\n"+
+				"  • Server name is spelled correctly\n"+
+				"  • Server is registered: alpacon server ls\n"+
+				"  • You have access to this server", serverName)
+		} else {
+			utils.CliError("Failed to upload to server '%s': %s\n\n"+
+				"Try these solutions:\n"+
+				"  • Check server connectivity: alpacon exec %s 'echo test'\n"+
+				"  • Verify destination path exists: alpacon exec %s 'ls -la %s'\n"+
+				"  • Check available disk space on server",
+				serverName, err, serverName, serverName, filepath.Dir(remotePath))
+		}
 		return err
 	}
 	wrappedSrc := fmt.Sprintf("[%s]", strings.Join(src, ", "))
@@ -173,12 +279,52 @@ func uploadObject(client *client.AlpaconClient, src []string, dest, username, gr
 }
 
 func downloadObject(client *client.AlpaconClient, src, dest, username, groupname string, recursive bool) error {
-	var err error
-	err = ftp.DownloadFile(client, src, dest, username, groupname, recursive)
+	// Extract server name for better error messages
+	serverName, remotePath := utils.SplitPath(src)
 
+	err := ftp.DownloadFile(client, src, dest, username, groupname, recursive)
 	if err != nil {
+		// Parse error and provide specific guidance
+		errStr := err.Error()
+		if strings.Contains(errStr, "no such file or directory") || strings.Contains(errStr, "file not found") {
+			utils.CliError("Source file not found: '%s' on server '%s'.\n\n"+
+				"Please check:\n"+
+				"  • File path is correct: %s\n"+
+				"  • File exists: alpacon exec %s 'ls -la %s'\n"+
+				"  • You have read permissions for the file\n"+
+				"  • For folders, use -r flag: alpacon cp -r %s %s",
+				remotePath, serverName, remotePath, serverName, filepath.Dir(remotePath), src, dest)
+		} else if strings.Contains(errStr, "permission denied") || strings.Contains(errStr, "access denied") {
+			utils.CliError("Permission denied downloading '%s' from server '%s'.\n\n"+
+				"Try these solutions:\n"+
+				"  • Download as root: alpacon cp -u root %s %s\n"+
+				"  • Download as file owner: alpacon cp -u OWNER %s %s\n"+
+				"  • Check file permissions: alpacon exec %s 'ls -la %s'",
+				remotePath, serverName, src, dest, src, dest, serverName, remotePath)
+		} else if strings.Contains(errStr, "server not found") || strings.Contains(errStr, "unknown host") {
+			utils.CliError("Server '%s' not found.\n\n"+
+				"Please check:\n"+
+				"  • Server name is spelled correctly\n"+
+				"  • Server is registered: alpacon server ls\n"+
+				"  • You have access to this server", serverName)
+		} else if strings.Contains(errStr, "download failed") {
+			utils.CliError("Download failed from server '%s': %s\n\n"+
+				"This might be due to:\n"+
+				"  • Network connectivity issues\n"+
+				"  • Server timeout (file too large)\n"+
+				"  • Insufficient local disk space\n"+
+				"  • Server-side file access issues",
+				serverName, err)
+		} else {
+			utils.CliError("Failed to download from server '%s': %s\n\n"+
+				"Try these solutions:\n"+
+				"  • Check server connectivity: alpacon exec %s 'echo test'\n"+
+				"  • Verify source file: alpacon exec %s 'file %s'\n"+
+				"  • Check local destination permissions",
+				serverName, err, serverName, serverName, remotePath)
+		}
 		return err
 	}
-	utils.CliInfo("Download request for %s to server %s successful.", src, dest)
+	utils.CliInfo("Download request for %s to %s successful.", src, dest)
 	return nil
 }

cmd/iam/group.go

@@ -17,7 +17,7 @@ var GroupCmd = &cobra.Command{
 		if err != nil {
 			return err
 		}
-		return errors.New("subcommand error")
+		return errors.New("a subcommand is required. Use 'alpacon group list', 'alpacon group create', 'alpacon group detail', 'alpacon group delete', or 'alpacon group member' to manage groups. Run 'alpacon group --help' for more information")
 	},
 }
 

cmd/iam/member.go

@@ -18,7 +18,7 @@ var MemberCmd = &cobra.Command{
 		if err != nil {
 			return err
 		}
-		return errors.New("subcommand error")
+		return errors.New("a subcommand is required. Use 'alpacon group member add' or 'alpacon group member delete' to manage group membership. Run 'alpacon group member --help' for more information")
 	},
 }
 

cmd/iam/member_add.go

@@ -62,6 +62,6 @@ func promptForRole() string {
 		if strings.ToLower(role) == "owner" || strings.ToLower(role) == "manager" || strings.ToLower(role) == "member" {
 			return role
 		}
-		fmt.Println("Invalid role. Please choose 'owner', 'manager', or 'member'.")
+		fmt.Println("Invalid role. Please choose 'owner', 'manager', or 'member'. Role determines the user's permissions within the group")
 	}
 }