refactor: apply empirically validated comprehension improvements

.github/workflows/integration.yml

@@ -3,6 +3,7 @@ name: Integration
 on:
   push:
     branches: [main]
+  workflow_dispatch:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -51,6 +52,5 @@ jobs:
       - name: Integration tests
         env:
           HL_TESTNET: "true"
-          HL_TEST_AGENT_KEY: ${{ secrets.HL_TEST_AGENT_KEY }}
-          HL_TEST_MASTER_KEY: ${{ secrets.HL_TEST_MASTER_KEY }}
+          HL_TEST_PRIVATE_KEY: ${{ secrets.HL_TEST_MASTER_KEY }}
         run: make test-integration

Makefile

@@ -10,13 +10,13 @@ BIN_DIR  := bin
 DIST_DIR := dist
 TEST_OUT := /tmp/hlgo-test.out
 
-.PHONY: build test test\:ci test-cover test-integration vet fmt lint tidy check clean install \
+.PHONY: build test test\:ci test-cover test-integration test-integration-live vet fmt lint tidy check clean install \
         build-linux build-darwin build-windows dist
 
-# run-tests-quiet: local-friendly test runner — shows only failures + summary.
-# Usage: $(call run-tests-quiet,<extra go test flags>)
-define run-tests-quiet
-	@go test -race -count=1 $(1) ./... 2>&1 | tee $(TEST_OUT); \
+# run-tests-quiet-pkgs: local-friendly test runner — shows only failures + summary.
+# Usage: $(call run-tests-quiet-pkgs,<extra go test flags>,<packages>)
+define run-tests-quiet-pkgs
+	@go test -race -count=1 $(1) $(2) 2>&1 | tee $(TEST_OUT); \
 	status=$${PIPESTATUS[0]}; \
 	echo ""; \
 	echo "──────────────────────────────────────────"; \
@@ -27,6 +27,12 @@ define run-tests-quiet
 	exit $$status
 endef
 
+# run-tests-quiet: local-friendly test runner — shows only failures + summary.
+# Usage: $(call run-tests-quiet,<extra go test flags>)
+define run-tests-quiet
+	$(call run-tests-quiet-pkgs,$(1),./...)
+endef
+
 # run-tests-verbose: CI-friendly — full verbose output + summary.
 # Usage: $(call run-tests-verbose,<extra go test flags>)
 define run-tests-verbose
@@ -59,9 +65,13 @@ test-cover:
 	@go tool cover -html=coverage.out -o coverage.html
 	@echo "Coverage report: coverage.html"
 
-## test-integration: run integration tests (requires testnet env vars)
+## test-integration: run safe integration tests (live account mutation tests are excluded)
 test-integration:
-	$(call run-tests-quiet,-tags=integration -timeout=5m)
+	$(call run-tests-quiet-pkgs,-tags=integration -timeout=5m -skip '^TestIntegration_AccountLive',./e2e)
+
+## test-integration-live: run destructive live account integration tests (requires HL_TEST_PRIVATE_KEY + HL_TEST_LIVE_CONFIG_JSON)
+test-integration-live:
+	$(call run-tests-quiet-pkgs,-tags=integration -timeout=5m -run '^TestIntegration_AccountLive',./e2e)
 
 ## vet: static analysis
 vet:

cmd/account.go

@@ -3,25 +3,17 @@ package cmd
 import "github.com/spf13/cobra"
 
 func newAccountCmd() *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "account",
-		Short: "Account transfers, withdrawals, and agent management",
-		Long: `Transfer USDC between spot and perp, withdraw to Arbitrum, manage agent
+	return newHelpCommandGroup(
+		"account",
+		"Account transfers, withdrawals, and agent management",
+		`Transfer USDC between spot and perp, withdraw to Arbitrum, manage agent
 wallet approvals, and perform cross-account transfers. Account commands
 sign with the configured private key via the user-signed path (chain ID 421614).`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			return cmd.Help()
-		},
-	}
-
-	cmd.AddCommand(
 		newAccountTransferCmd(),
 		newAccountWithdrawCmd(),
 		newAccountClassTransferCmd(),
 		newAccountSendAssetCmd(),
 		newAccountApproveAgentCmd(),
 		newAccountSetAbstractionCmd(),
 	)
-
-	return cmd
 }

cmd/account_approve_agent.go

@@ -20,11 +20,9 @@ func newAccountApproveAgentCmd() *cobra.Command {
 Note: Hyperliquid may charge an activation fee when first approving an agent.`,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			cfg := config.FromContext(cmd.Context())
-			agent, _ := cmd.Flags().GetString("agent")   //nolint:errcheck // known flag
-			name, _ := cmd.Flags().GetString("name")     //nolint:errcheck // known flag
-			revoke, _ := cmd.Flags().GetBool("revoke")   //nolint:errcheck // known flag
-			confirm, _ := cmd.Flags().GetBool("confirm") //nolint:errcheck // known flag
-			yes, _ := cmd.Flags().GetBool("yes")         //nolint:errcheck // known flag
+			agent, _ := cmd.Flags().GetString("agent") //nolint:errcheck // known flag
+			name, _ := cmd.Flags().GetString("name")   //nolint:errcheck // known flag
+			revoke, _ := cmd.Flags().GetBool("revoke") //nolint:errcheck // known flag
 
 			if !common.IsHexAddress(agent) {
 				return output.NewCLIError(output.ErrValidation, "invalid agent address").
@@ -34,7 +32,7 @@ Note: Hyperliquid may charge an activation fee when first approving an agent.`,
 			agentName := strings.TrimSpace(name)
 			switch {
 			case revoke:
-				if err := requireConfirm("approve-agent --revoke", confirm || yes, cfg.DryRun); err != nil {
+				if err := requireConfirm("approve-agent --revoke", confirmationAccepted(cmd), cfg.DryRun); err != nil {
 					return err
 				}
 				agentName = ""
@@ -52,11 +50,12 @@ Note: Hyperliquid may charge an activation fee when first approving an agent.`,
 				return err
 			}
 
-			raw, err := exec.ApproveAgent(cmd.Context(), exchange.ApproveAgentInput{
+			input := exchange.ApproveAgentInput{
 				AgentAddress: strings.ToLower(agent),
 				AgentName:    agentName,
 				DryRun:       cfg.DryRun,
-			})
+			}
+			raw, err := exec.ApproveAgent(cmd.Context(), input)
 			if err != nil {
 				return err
 			}
@@ -70,8 +69,7 @@ Note: Hyperliquid may charge an activation fee when first approving an agent.`,
 	cmd.Flags().Bool("revoke", false, "revoke agent by setting an empty label")
 	cmd.Flags().Bool("confirm", false, "confirm execution for revoke flow")
 	cmd.Flags().Bool("yes", false, "alias for --confirm")
-	//nolint:errcheck // MarkFlagRequired on known flags never fails
-	cmd.MarkFlagRequired("agent")
+	mustMarkRequiredFlags(cmd, "agent")
 
 	return cmd
 }

cmd/account_class_transfer.go

@@ -1,57 +1,13 @@
 package cmd
 
-import (
-	"github.com/shopspring/decimal"
-	"github.com/spf13/cobra"
-
-	"github.com/timbrinded/hlgo/pkg/config"
-	"github.com/timbrinded/hlgo/pkg/exchange"
-	"github.com/timbrinded/hlgo/pkg/output"
-)
+import "github.com/spf13/cobra"
 
 func newAccountClassTransferCmd() *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "class-transfer",
-		Short: "Alias of transfer using usdClassTransfer semantics",
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			cfg := config.FromContext(cmd.Context())
-			amountStr, _ := cmd.Flags().GetString("amount") //nolint:errcheck // known flag
-			toPerp, _ := cmd.Flags().GetBool("to-perp")     //nolint:errcheck // known flag
-			toSpot, _ := cmd.Flags().GetBool("to-spot")     //nolint:errcheck // known flag
-
-			if toPerp == toSpot {
-				return output.NewCLIError(output.ErrValidation, "exactly one of --to-perp or --to-spot is required")
-			}
-
-			amount, err := decimal.NewFromString(amountStr)
-			if err != nil {
-				return output.NewCLIError(output.ErrValidation, "invalid amount").
-					WithDetails("value", amountStr)
-			}
-
-			exec, err := buildExecutor(cfg)
-			if err != nil {
-				return err
-			}
-
-			raw, err := exec.USDClassTransfer(cmd.Context(), exchange.USDClassTransferInput{
-				Amount: amount,
-				ToPerp: toPerp,
-				DryRun: cfg.DryRun,
-			})
-			if err != nil {
-				return err
-			}
-
-			return printResult(cmd, cfg, raw, nil)
-		},
-	}
-
-	cmd.Flags().String("amount", "", "transfer amount")
-	cmd.Flags().Bool("to-perp", false, "transfer toward perp class")
-	cmd.Flags().Bool("to-spot", false, "transfer toward spot class")
-	//nolint:errcheck // MarkFlagRequired on known flags never fails
-	cmd.MarkFlagRequired("amount")
-
-	return cmd
+	return newUSDClassTransferCmd(
+		"class-transfer",
+		"Alias of transfer using usdClassTransfer semantics",
+		"transfer amount",
+		"transfer toward perp class",
+		"transfer toward spot class",
+	)
 }

cmd/account_send_asset.go

@@ -1,15 +1,10 @@
 package cmd
 
 import (
-	"strings"
-
-	"github.com/ethereum/go-ethereum/common"
-	"github.com/shopspring/decimal"
 	"github.com/spf13/cobra"
 
 	"github.com/timbrinded/hlgo/pkg/config"
 	"github.com/timbrinded/hlgo/pkg/exchange"
-	"github.com/timbrinded/hlgo/pkg/output"
 )
 
 func newAccountSendAssetCmd() *cobra.Command {
@@ -21,38 +16,23 @@ func newAccountSendAssetCmd() *cobra.Command {
 			destination, _ := cmd.Flags().GetString("destination") //nolint:errcheck // known flag
 			token, _ := cmd.Flags().GetString("token")             //nolint:errcheck // known flag
 			amountStr, _ := cmd.Flags().GetString("amount")        //nolint:errcheck // known flag
-			confirm, _ := cmd.Flags().GetBool("confirm")           //nolint:errcheck // known flag
-			yes, _ := cmd.Flags().GetBool("yes")                   //nolint:errcheck // known flag
 
-			if err := requireConfirm("send-asset", confirm || yes, cfg.DryRun); err != nil {
+			if err := requireConfirm("send-asset", confirmationAccepted(cmd), cfg.DryRun); err != nil {
 				return err
 			}
 
-			if !common.IsHexAddress(destination) {
-				return output.NewCLIError(output.ErrValidation, "invalid destination address").
-					WithDetails("destination", destination)
-			}
-			if strings.TrimSpace(token) == "" {
-				return output.NewCLIError(output.ErrValidation, "token is required")
-			}
-
-			amount, err := decimal.NewFromString(amountStr)
+			amount, err := parseDecimalField("amount", amountStr)
 			if err != nil {
-				return output.NewCLIError(output.ErrValidation, "invalid amount").
-					WithDetails("value", amountStr)
+				return err
 			}
 
 			exec, err := buildExecutor(cfg)
 			if err != nil {
 				return err
 			}
 
-			raw, err := exec.SpotSend(cmd.Context(), exchange.SpotSendInput{
-				Destination: strings.ToLower(destination),
-				Token:       token,
-				Amount:      amount,
-				DryRun:      cfg.DryRun,
-			})
+			input := exchange.SpotSendInput{Destination: destination, Token: token, Amount: amount, DryRun: cfg.DryRun}
+			raw, err := exec.SpotSend(cmd.Context(), input)
 			if err != nil {
 				return err
 			}
@@ -67,10 +47,7 @@ func newAccountSendAssetCmd() *cobra.Command {
 	cmd.Flags().Bool("confirm", false, "confirm execution for asset send")
 	cmd.Flags().Bool("yes", false, "alias for --confirm")
 
-	for _, required := range []string{"destination", "token", "amount"} {
-		//nolint:errcheck // MarkFlagRequired on known flags never fails
-		cmd.MarkFlagRequired(required)
-	}
+	mustMarkRequiredFlags(cmd, "destination", "token", "amount")
 
 	return cmd
 }

cmd/account_set_abstraction.go

@@ -1,22 +1,12 @@
 package cmd
 
 import (
-	"strings"
-
-	"github.com/ethereum/go-ethereum/common"
 	"github.com/spf13/cobra"
 
 	"github.com/timbrinded/hlgo/pkg/config"
 	"github.com/timbrinded/hlgo/pkg/exchange"
-	"github.com/timbrinded/hlgo/pkg/output"
 )
 
-var allowedAbstractions = map[string]struct{}{
-	"unifiedAccount":  {},
-	"portfolioMargin": {},
-	"disabled":        {},
-}
-
 func newAccountSetAbstractionCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "set-abstraction",
@@ -26,30 +16,13 @@ func newAccountSetAbstractionCmd() *cobra.Command {
 			user, _ := cmd.Flags().GetString("user")               //nolint:errcheck // known flag
 			abstraction, _ := cmd.Flags().GetString("abstraction") //nolint:errcheck // known flag
 
-			if !common.IsHexAddress(user) {
-				return output.NewCLIError(output.ErrValidation, "invalid user address").
-					WithDetails("user", user)
-			}
-			abstraction = strings.TrimSpace(abstraction)
-			if abstraction == "" {
-				return output.NewCLIError(output.ErrValidation, "abstraction is required")
-			}
-			if _, ok := allowedAbstractions[abstraction]; !ok {
-				return output.NewCLIError(output.ErrValidation, "unsupported abstraction value").
-					WithDetails("value", abstraction).
-					WithDetails("allowed", []string{"unifiedAccount", "portfolioMargin", "disabled"})
-			}
-
 			exec, err := buildExecutor(cfg)
 			if err != nil {
 				return err
 			}
 
-			raw, err := exec.UserSetAbstraction(cmd.Context(), exchange.UserSetAbstractionInput{
-				User:        strings.ToLower(user),
-				Abstraction: abstraction,
-				DryRun:      cfg.DryRun,
-			})
+			input := exchange.UserSetAbstractionInput{User: user, Abstraction: abstraction, DryRun: cfg.DryRun}
+			raw, err := exec.UserSetAbstraction(cmd.Context(), input)
 			if err != nil {
 				return err
 			}
@@ -61,10 +34,7 @@ func newAccountSetAbstractionCmd() *cobra.Command {
 	cmd.Flags().String("user", "", "user address")
 	cmd.Flags().String("abstraction", "", "abstraction string")
 
-	for _, required := range []string{"user", "abstraction"} {
-		//nolint:errcheck // MarkFlagRequired on known flags never fails
-		cmd.MarkFlagRequired(required)
-	}
+	mustMarkRequiredFlags(cmd, "user", "abstraction")
 
 	return cmd
 }

cmd/account_test.go

@@ -191,6 +191,29 @@ func TestAccountApproveAgent_NameRequiredWithoutRevoke(t *testing.T) {
 	}
 }
 
+func TestAccountApproveAgent_InvalidAddressPrecedesNameValidation(t *testing.T) {
+	_, _, run := newTestRootWithServer(t, "")
+
+	err := run("account", "approve-agent",
+		"--agent", "bad",
+		"--dry-run",
+	)
+	if err == nil {
+		t.Fatal("expected validation error for invalid agent address")
+	}
+
+	var cliErr *output.CLIError
+	if !errors.As(err, &cliErr) {
+		t.Fatalf("expected CLIError, got %T", err)
+	}
+	if cliErr.Code != output.ErrValidation {
+		t.Fatalf("code = %q, want %q", cliErr.Code, output.ErrValidation)
+	}
+	if cliErr.Message != "invalid agent address" {
+		t.Fatalf("message = %q, want %q", cliErr.Message, "invalid agent address")
+	}
+}
+
 func TestAccountSetAbstraction_DryRun(t *testing.T) {
 	stdout, _, run := newTestRootWithServer(t, "")