Add error tracking and reporting system (#39)

* Add error tracking and reporting system

* need an ability to cancel a spinner action if an error occurs while running the action

Author: jhaynie

.github/workflows/go.yml

@@ -17,6 +17,9 @@ jobs:
       with:
         go-version: '1.24'
 
+    - name: Generate Error Codes
+      run: go generate ./...
+
     - name: Build
       run: go build -v .
 

.gitignore

@@ -4,4 +4,5 @@ cli
 dist/
 **/.DS_Store
 /my*test*
-/test*
+/test*
+.agentuity-crash-*

Makefile

@@ -1,7 +1,11 @@
-.PHONY: build fmt
+.PHONY: build fmt generate
 
-build: fmt
+build: fmt generate
 	@go build -o agentuity
 
 fmt:
-	@go fmt ./...
+	@go fmt ./...
+
+generate:
+	@echo "Running go generate..."
+	@go generate ./...

README.md

@@ -104,6 +104,20 @@ For more detailed information about any command, you can use:
 agentuity [command] --help
 ```
 
+## Development
+
+### Error Code System
+
+The CLI uses a centralized error code system to provide consistent error messages and codes. Error codes are defined in `error_codes.yaml` at the root of the project and are automatically generated into Go code.
+
+To add a new error code:
+
+1. Edit `error_codes.yaml` and add a new entry with a unique code and descriptive message
+2. Run `go generate ./...` to update the Go code
+3. Use the generated error type in your code with `errsystem.New(errsystem.ErrYourError, err)`
+
+For more details, see the [Error Code System documentation](tools/README.md).
+
 ## License
 
 See the [LICENSE](LICENSE.md) file for details.

cmd/agent.go

@@ -8,6 +8,7 @@ import (
 	"strings"
 
 	"github.com/agentuity/cli/internal/agent"
+	"github.com/agentuity/cli/internal/errsystem"
 	"github.com/agentuity/cli/internal/project"
 	"github.com/agentuity/cli/internal/templates"
 	"github.com/agentuity/cli/internal/tui"
@@ -37,7 +38,7 @@ var agentDeleteCmd = &cobra.Command{
 		logger := env.NewLogger(cmd)
 		apikey := viper.GetString("auth.api_key")
 		if apikey == "" {
-			logger.Fatal("you are not logged in")
+			logger.Fatal("You are not logged in. Please run `agentuity login` to login.")
 		}
 		theproject := ensureProject(cmd)
 		apiUrl, _ := getURLs(logger)
@@ -68,7 +69,7 @@ var agentDeleteCmd = &cobra.Command{
 			var err error
 			deleted, err = agent.DeleteAgents(logger, apiUrl, apikey, theproject.Project.ProjectId, selected)
 			if err != nil {
-				logger.Fatal("failed to delete Agents: %s", err)
+				errsystem.New(errsystem.ErrApiRequest, err, errsystem.WithContextMessage("Failed to delete agents")).ShowErrorAndExit()
 			}
 			for _, key := range keys {
 				agent := state[key]
@@ -83,7 +84,7 @@ var agentDeleteCmd = &cobra.Command{
 			return
 		}
 
-		tui.ShowSpinner(logger, "Deleting Agents ...", action)
+		tui.ShowSpinner("Deleting Agents ...", action)
 		tui.ShowSuccess("%s deleted successfully", util.Pluralize(len(deleted), "Agent", "Agents"))
 	},
 }
@@ -96,14 +97,14 @@ var agentCreateCmd = &cobra.Command{
 		logger := env.NewLogger(cmd)
 		apikey := viper.GetString("auth.api_key")
 		if apikey == "" {
-			logger.Fatal("you are not logged in")
+			logger.Fatal("You are not logged in. Please run `agentuity login` to login.")
 		}
 		theproject := ensureProject(cmd)
 		apiUrl, _ := getURLs(logger)
 
 		remoteAgents, err := getAgentList(logger, apiUrl, apikey, theproject)
 		if err != nil {
-			logger.Fatal("failed to list Agents: %s", err)
+			errsystem.New(errsystem.ErrApiRequest, err, errsystem.WithContextMessage("Failed to get agent list")).ShowErrorAndExit()
 		}
 
 		initScreenWithLogo()
@@ -122,12 +123,12 @@ var agentCreateCmd = &cobra.Command{
 		action := func() {
 			agentID, err := agent.CreateAgent(logger, apiUrl, apikey, theproject.Project.ProjectId, name, description)
 			if err != nil {
-				logger.Fatal("failed to create agent: %s", err)
+				errsystem.New(errsystem.ErrApiRequest, err, errsystem.WithContextMessage("Failed to create agent")).ShowErrorAndExit()
 			}
 
 			rules, err := templates.LoadTemplateRuleForIdentifier(theproject.Project.Bundler.Identifier)
 			if err != nil {
-				logger.Fatal("failed to load template rules for %s: %s", theproject.Project.Bundler.Identifier, err)
+				errsystem.New(errsystem.ErrInvalidConfiguration, err, errsystem.WithAttributes(map[string]any{"identifier": theproject.Project.Bundler.Identifier})).ShowErrorAndExit()
 			}
 
 			if err := rules.NewAgent(templates.TemplateContext{
@@ -136,7 +137,7 @@ var agentCreateCmd = &cobra.Command{
 				Description: description,
 				ProjectDir:  theproject.Dir,
 			}); err != nil {
-				logger.Fatal("failed to create agent: %s", err)
+				errsystem.New(errsystem.ErrApiRequest, err, errsystem.WithAttributes(map[string]any{"name": name})).ShowErrorAndExit()
 			}
 
 			theproject.Project.Agents = append(theproject.Project.Agents, project.AgentConfig{
@@ -146,10 +147,10 @@ var agentCreateCmd = &cobra.Command{
 			})
 
 			if err := theproject.Project.Save(theproject.Dir); err != nil {
-				logger.Fatal("failed to save project: %s", err)
+				errsystem.New(errsystem.ErrSaveProject, err, errsystem.WithContextMessage("Failed to save project to disk")).ShowErrorAndExit()
 			}
 		}
-		tui.ShowSpinner(logger, "Creating agent ...", action)
+		tui.ShowSpinner("Creating agent ...", action)
 		tui.ShowSuccess("Agent created successfully")
 	},
 }
@@ -167,7 +168,7 @@ func getAgentList(logger logger.Logger, apiUrl string, apikey string, project pr
 	action := func() {
 		remoteAgents, err = agent.ListAgents(logger, apiUrl, apikey, project.Project.ProjectId)
 	}
-	tui.ShowSpinner(logger, "Fetching Agents ...", action)
+	tui.ShowSpinner("Fetching Agents ...", action)
 	return remoteAgents, err
 }
 
@@ -178,12 +179,14 @@ func normalAgentName(name string) string {
 func reconcileAgentList(logger logger.Logger, apiUrl string, apikey string, theproject projectContext) ([]string, map[string]agentListState) {
 	remoteAgents, err := getAgentList(logger, apiUrl, apikey, theproject)
 	if err != nil {
-		logger.Fatal("failed to fetch Agents for project: %s", err)
+		errsystem.New(errsystem.ErrApiRequest, err, errsystem.WithContextMessage("Failed to get agent list")).ShowErrorAndExit()
 	}
 
 	rules, err := templates.LoadTemplateRuleForIdentifier(theproject.Project.Bundler.Identifier)
 	if err != nil {
-		logger.Fatal("failed to load the agent template for %s. %s", theproject.Project.Bundler.Identifier, err)
+		errsystem.New(errsystem.ErrInvalidConfiguration, err,
+			errsystem.WithContextMessage("Failed loading template rule"),
+			errsystem.WithAttributes(map[string]any{"identifier": theproject.Project.Bundler.Identifier})).ShowErrorAndExit()
 	}
 
 	// make a map of the agents in the agentuity config file
@@ -207,7 +210,7 @@ func reconcileAgentList(logger logger.Logger, apiUrl string, apikey string, thep
 	}
 	localAgents, err := util.ListDir(agentSrcDir)
 	if err != nil {
-		logger.Fatal("failed to list local Agents: %s", err)
+		errsystem.New(errsystem.ErrListFilesAndDirectories, err, errsystem.WithContextMessage("Failed to list agent source directory")).ShowErrorAndExit()
 	}
 	for _, filename := range localAgents {
 		agentName := filepath.Base(filepath.Dir(filename))
@@ -337,13 +340,13 @@ func showAgentWarnings(remoteIssues int, localIssues int, deploying bool) bool {
 
 var agentListCmd = &cobra.Command{
 	Use:     "list",
-	Short:   "List all the Agents in the project which are deployed",
+	Short:   "List all Agents in the project",
 	Aliases: []string{"ls"},
 	Run: func(cmd *cobra.Command, args []string) {
 		logger := env.NewLogger(cmd)
 		apikey := viper.GetString("auth.api_key")
 		if apikey == "" {
-			logger.Fatal("you are not logged in")
+			logger.Fatal("You are not logged in. Please run `agentuity login` to login.")
 		}
 		project := ensureProject(cmd)
 		apiUrl, _ := getURLs(logger)
@@ -359,7 +362,7 @@ var agentListCmd = &cobra.Command{
 
 		root, localIssues, remoteIssues, err := buildAgentTree(keys, state, project)
 		if err != nil {
-			logger.Fatal("%s", err)
+			errsystem.New(errsystem.ErrInvalidConfiguration, err, errsystem.WithContextMessage("Failed to build agent tree")).ShowErrorAndExit()
 		}
 
 		fmt.Println(root)

cmd/auth.go

@@ -2,6 +2,7 @@ package cmd
 
 import (
 	"github.com/agentuity/cli/internal/auth"
+	"github.com/agentuity/cli/internal/errsystem"
 	"github.com/agentuity/cli/internal/tui"
 	"github.com/agentuity/go-common/env"
 	"github.com/spf13/cobra"
@@ -25,12 +26,14 @@ var authLoginCmd = &cobra.Command{
 		initScreenWithLogo()
 		authResult, err := auth.Login(logger, appUrl)
 		if err != nil {
-			logger.Fatal("failed to login: %s", err)
+			errsystem.New(errsystem.ErrAuthenticateUser, err,
+				errsystem.WithContextMessage("Failed to login")).ShowErrorAndExit()
 		}
 		viper.Set("auth.api_key", authResult.APIKey)
 		viper.Set("auth.user_id", authResult.UserId)
 		if err := viper.WriteConfig(); err != nil {
-			logger.Fatal("failed to write config: %s", err)
+			errsystem.New(errsystem.ErrWriteConfigurationFile, err,
+				errsystem.WithContextMessage("Failed to write viper config")).ShowErrorAndExit()
 		}
 		tui.ShowSuccess("You are now logged in")
 	},
@@ -44,16 +47,18 @@ var authLogoutCmd = &cobra.Command{
 		_, appUrl := getURLs(logger)
 		token := viper.GetString("auth.api_key")
 		if token == "" {
-			logger.Fatal("you are not logged in")
+			logger.Fatal("You are not logged in. Please run `agentuity login` to login.")
 		}
 		viper.Set("auth.api_key", "")
 		viper.Set("auth.user_id", "")
 		if err := viper.WriteConfig(); err != nil {
-			logger.Fatal("failed to write config: %s", err)
+			errsystem.New(errsystem.ErrWriteConfigurationFile, err,
+				errsystem.WithContextMessage("Failed to write viper config")).ShowErrorAndExit()
 		}
 		initScreenWithLogo()
 		if err := auth.Logout(logger, appUrl, token); err != nil {
-			logger.Fatal("failed to logout: %s", err)
+			errsystem.New(errsystem.ErrApiRequest, err,
+				errsystem.WithContextMessage("Failed to logout")).ShowErrorAndExit()
 		}
 		tui.ShowSuccess("You have been logged out")
 	},
@@ -66,11 +71,11 @@ var authWhoamiCmd = &cobra.Command{
 		logger := env.NewLogger(cmd)
 		apikey := viper.GetString("auth.api_key")
 		if apikey == "" {
-			logger.Fatal("you are not logged in")
+			logger.Fatal("You are not logged in. Please run `agentuity login` to login.")
 		}
 		userId := viper.GetString("auth.user_id")
 		if userId == "" {
-			logger.Fatal("you are not logged in")
+			logger.Fatal("You are not logged in. Please run `agentuity login` to login.")
 		}
 		logger.Info("You are logged in with user id: %s", userId)
 	},

cmd/bundle.go

@@ -5,6 +5,7 @@ import (
 	"time"
 
 	"github.com/agentuity/cli/internal/bundler"
+	"github.com/agentuity/cli/internal/errsystem"
 	"github.com/spf13/cobra"
 )
 
@@ -22,7 +23,7 @@ var bundleCmd = &cobra.Command{
 			ProjectDir: projectContext.Dir,
 			Production: production,
 		}); err != nil {
-			projectContext.Logger.Fatal("%s", err)
+			errsystem.New(errsystem.ErrInvalidConfiguration, err, errsystem.WithContextMessage("Failed to bundle project")).ShowErrorAndExit()
 		}
 		projectContext.Logger.Debug("bundled in %s", time.Since(started))
 	},