Refactor codebase

internal/auth/claude/anthropic_auth.go

@@ -1,3 +1,6 @@
+// Package claude provides OAuth2 authentication functionality for Anthropic's Claude API.
+// This package implements the complete OAuth2 flow with PKCE (Proof Key for Code Exchange)
+// for secure authentication with Claude API, including token exchange, refresh, and storage.
 package claude
 
 import (
@@ -22,7 +25,8 @@ const (
 	redirectURI       = "http://localhost:54545/callback"
 )
 
-// Parse token response
+// tokenResponse represents the response structure from Anthropic's OAuth token endpoint.
+// It contains access token, refresh token, and associated user/organization information.
 type tokenResponse struct {
 	AccessToken  string `json:"access_token"`
 	RefreshToken string `json:"refresh_token"`
@@ -38,19 +42,39 @@ type tokenResponse struct {
 	} `json:"account"`
 }
 
-// ClaudeAuth handles Anthropic OAuth2 authentication flow
+// ClaudeAuth handles Anthropic OAuth2 authentication flow.
+// It provides methods for generating authorization URLs, exchanging codes for tokens,
+// and refreshing expired tokens using PKCE for enhanced security.
 type ClaudeAuth struct {
 	httpClient *http.Client
 }
 
-// NewClaudeAuth creates a new Anthropic authentication service
+// NewClaudeAuth creates a new Anthropic authentication service.
+// It initializes the HTTP client with proxy settings from the configuration.
+//
+// Parameters:
+//   - cfg: The application configuration containing proxy settings
+//
+// Returns:
+//   - *ClaudeAuth: A new Claude authentication service instance
 func NewClaudeAuth(cfg *config.Config) *ClaudeAuth {
 	return &ClaudeAuth{
 		httpClient: util.SetProxy(cfg, &http.Client{}),
 	}
 }
 
-// GenerateAuthURL creates the OAuth authorization URL with PKCE
+// GenerateAuthURL creates the OAuth authorization URL with PKCE.
+// This method generates a secure authorization URL including PKCE challenge codes
+// for the OAuth2 flow with Anthropic's API.
+//
+// Parameters:
+//   - state: A random state parameter for CSRF protection
+//   - pkceCodes: The PKCE codes for secure code exchange
+//
+// Returns:
+//   - string: The complete authorization URL
+//   - string: The state parameter for verification
+//   - error: An error if PKCE codes are missing or URL generation fails
 func (o *ClaudeAuth) GenerateAuthURL(state string, pkceCodes *PKCECodes) (string, string, error) {
 	if pkceCodes == nil {
 		return "", "", fmt.Errorf("PKCE codes are required")
@@ -71,6 +95,15 @@ func (o *ClaudeAuth) GenerateAuthURL(state string, pkceCodes *PKCECodes) (string
 	return authURL, state, nil
 }
 
+// parseCodeAndState extracts the authorization code and state from the callback response.
+// It handles the parsing of the code parameter which may contain additional fragments.
+//
+// Parameters:
+//   - code: The raw code parameter from the OAuth callback
+//
+// Returns:
+//   - parsedCode: The extracted authorization code
+//   - parsedState: The extracted state parameter if present
 func (c *ClaudeAuth) parseCodeAndState(code string) (parsedCode, parsedState string) {
 	splits := strings.Split(code, "#")
 	parsedCode = splits[0]
@@ -80,7 +113,19 @@ func (c *ClaudeAuth) parseCodeAndState(code string) (parsedCode, parsedState str
 	return
 }
 
-// ExchangeCodeForTokens exchanges authorization code for access tokens
+// ExchangeCodeForTokens exchanges authorization code for access tokens.
+// This method implements the OAuth2 token exchange flow using PKCE for security.
+// It sends the authorization code along with PKCE verifier to get access and refresh tokens.
+//
+// Parameters:
+//   - ctx: The context for the request
+//   - code: The authorization code received from OAuth callback
+//   - state: The state parameter for verification
+//   - pkceCodes: The PKCE codes for secure verification
+//
+// Returns:
+//   - *ClaudeAuthBundle: The complete authentication bundle with tokens
+//   - error: An error if token exchange fails
 func (o *ClaudeAuth) ExchangeCodeForTokens(ctx context.Context, code, state string, pkceCodes *PKCECodes) (*ClaudeAuthBundle, error) {
 	if pkceCodes == nil {
 		return nil, fmt.Errorf("PKCE codes are required for token exchange")
@@ -121,7 +166,9 @@ func (o *ClaudeAuth) ExchangeCodeForTokens(ctx context.Context, code, state stri
 		return nil, fmt.Errorf("token exchange request failed: %w", err)
 	}
 	defer func() {
-		_ = resp.Body.Close()
+		if errClose := resp.Body.Close(); errClose != nil {
+			log.Errorf("failed to close response body: %v", errClose)
+		}
 	}()
 
 	body, err := io.ReadAll(resp.Body)
@@ -157,7 +204,17 @@ func (o *ClaudeAuth) ExchangeCodeForTokens(ctx context.Context, code, state stri
 	return bundle, nil
 }
 
-// RefreshTokens refreshes the access token using the refresh token
+// RefreshTokens refreshes the access token using the refresh token.
+// This method exchanges a valid refresh token for a new access token,
+// extending the user's authenticated session.
+//
+// Parameters:
+//   - ctx: The context for the request
+//   - refreshToken: The refresh token to use for getting new access token
+//
+// Returns:
+//   - *ClaudeTokenData: The new token data with updated access token
+//   - error: An error if token refresh fails
 func (o *ClaudeAuth) RefreshTokens(ctx context.Context, refreshToken string) (*ClaudeTokenData, error) {
 	if refreshToken == "" {
 		return nil, fmt.Errorf("refresh token is required")
@@ -215,7 +272,15 @@ func (o *ClaudeAuth) RefreshTokens(ctx context.Context, refreshToken string) (*C
 	}, nil
 }
 
-// CreateTokenStorage creates a new ClaudeTokenStorage from auth bundle and user info
+// CreateTokenStorage creates a new ClaudeTokenStorage from auth bundle and user info.
+// This method converts the authentication bundle into a token storage structure
+// suitable for persistence and later use.
+//
+// Parameters:
+//   - bundle: The authentication bundle containing token data
+//
+// Returns:
+//   - *ClaudeTokenStorage: A new token storage instance
 func (o *ClaudeAuth) CreateTokenStorage(bundle *ClaudeAuthBundle) *ClaudeTokenStorage {
 	storage := &ClaudeTokenStorage{
 		AccessToken:  bundle.TokenData.AccessToken,
@@ -228,7 +293,18 @@ func (o *ClaudeAuth) CreateTokenStorage(bundle *ClaudeAuthBundle) *ClaudeTokenSt
 	return storage
 }
 
-// RefreshTokensWithRetry refreshes tokens with automatic retry logic
+// RefreshTokensWithRetry refreshes tokens with automatic retry logic.
+// This method implements exponential backoff retry logic for token refresh operations,
+// providing resilience against temporary network or service issues.
+//
+// Parameters:
+//   - ctx: The context for the request
+//   - refreshToken: The refresh token to use
+//   - maxRetries: The maximum number of retry attempts
+//
+// Returns:
+//   - *ClaudeTokenData: The refreshed token data
+//   - error: An error if all retry attempts fail
 func (o *ClaudeAuth) RefreshTokensWithRetry(ctx context.Context, refreshToken string, maxRetries int) (*ClaudeTokenData, error) {
 	var lastErr error
 
@@ -254,7 +330,13 @@ func (o *ClaudeAuth) RefreshTokensWithRetry(ctx context.Context, refreshToken st
 	return nil, fmt.Errorf("token refresh failed after %d attempts: %w", maxRetries, lastErr)
 }
 
-// UpdateTokenStorage updates an existing token storage with new token data
+// UpdateTokenStorage updates an existing token storage with new token data.
+// This method refreshes the token storage with newly obtained access and refresh tokens,
+// updating timestamps and expiration information.
+//
+// Parameters:
+//   - storage: The existing token storage to update
+//   - tokenData: The new token data to apply
 func (o *ClaudeAuth) UpdateTokenStorage(storage *ClaudeTokenStorage, tokenData *ClaudeTokenData) {
 	storage.AccessToken = tokenData.AccessToken
 	storage.RefreshToken = tokenData.RefreshToken

internal/auth/claude/errors.go

@@ -1,3 +1,6 @@
+// Package claude provides authentication and token management functionality
+// for Anthropic's Claude AI services. It handles OAuth2 token storage, serialization,
+// and retrieval for maintaining authenticated sessions with the Claude API.
 package claude
 
 import (
@@ -6,14 +9,19 @@ import (
 	"net/http"
 )
 
-// OAuthError represents an OAuth-specific error
+// OAuthError represents an OAuth-specific error.
 type OAuthError struct {
-	Code        string `json:"error"`
+	// Code is the OAuth error code.
+	Code string `json:"error"`
+	// Description is a human-readable description of the error.
 	Description string `json:"error_description,omitempty"`
-	URI         string `json:"error_uri,omitempty"`
-	StatusCode  int    `json:"-"`
+	// URI is a URI identifying a human-readable web page with information about the error.
+	URI string `json:"error_uri,omitempty"`
+	// StatusCode is the HTTP status code associated with the error.
+	StatusCode int `json:"-"`
 }
 
+// Error returns a string representation of the OAuth error.
 func (e *OAuthError) Error() string {
 	if e.Description != "" {
 		return fmt.Sprintf("OAuth error %s: %s", e.Code, e.Description)
@@ -21,7 +29,7 @@ func (e *OAuthError) Error() string {
 	return fmt.Sprintf("OAuth error: %s", e.Code)
 }
 
-// NewOAuthError creates a new OAuth error
+// NewOAuthError creates a new OAuth error with the specified code, description, and status code.
 func NewOAuthError(code, description string, statusCode int) *OAuthError {
 	return &OAuthError{
 		Code:        code,
@@ -30,14 +38,19 @@ func NewOAuthError(code, description string, statusCode int) *OAuthError {
 	}
 }
 
-// AuthenticationError represents authentication-related errors
+// AuthenticationError represents authentication-related errors.
 type AuthenticationError struct {
-	Type    string `json:"type"`
+	// Type is the type of authentication error.
+	Type string `json:"type"`
+	// Message is a human-readable message describing the error.
 	Message string `json:"message"`
-	Code    int    `json:"code"`
-	Cause   error  `json:"-"`
+	// Code is the HTTP status code associated with the error.
+	Code int `json:"code"`
+	// Cause is the underlying error that caused this authentication error.
+	Cause error `json:"-"`
 }
 
+// Error returns a string representation of the authentication error.
 func (e *AuthenticationError) Error() string {
 	if e.Cause != nil {
 		return fmt.Sprintf("%s: %s (caused by: %v)", e.Type, e.Message, e.Cause)
@@ -45,44 +58,50 @@ func (e *AuthenticationError) Error() string {
 	return fmt.Sprintf("%s: %s", e.Type, e.Message)
 }
 
-// Common authentication error types
+// Common authentication error types.
 var (
-	ErrTokenExpired = &AuthenticationError{
-		Type:    "token_expired",
-		Message: "Access token has expired",
-		Code:    http.StatusUnauthorized,
-	}
+	// ErrTokenExpired = &AuthenticationError{
+	// 	Type:    "token_expired",
+	// 	Message: "Access token has expired",
+	// 	Code:    http.StatusUnauthorized,
+	// }
 
+	// ErrInvalidState represents an error for invalid OAuth state parameter.
 	ErrInvalidState = &AuthenticationError{
 		Type:    "invalid_state",
 		Message: "OAuth state parameter is invalid",
 		Code:    http.StatusBadRequest,
 	}
 
+	// ErrCodeExchangeFailed represents an error when exchanging authorization code for tokens fails.
 	ErrCodeExchangeFailed = &AuthenticationError{
 		Type:    "code_exchange_failed",
 		Message: "Failed to exchange authorization code for tokens",
 		Code:    http.StatusBadRequest,
 	}
 
+	// ErrServerStartFailed represents an error when starting the OAuth callback server fails.
 	ErrServerStartFailed = &AuthenticationError{
 		Type:    "server_start_failed",
 		Message: "Failed to start OAuth callback server",
 		Code:    http.StatusInternalServerError,
 	}
 
+	// ErrPortInUse represents an error when the OAuth callback port is already in use.
 	ErrPortInUse = &AuthenticationError{
 		Type:    "port_in_use",
 		Message: "OAuth callback port is already in use",
 		Code:    13, // Special exit code for port-in-use
 	}
 
+	// ErrCallbackTimeout represents an error when waiting for OAuth callback times out.
 	ErrCallbackTimeout = &AuthenticationError{
 		Type:    "callback_timeout",
 		Message: "Timeout waiting for OAuth callback",
 		Code:    http.StatusRequestTimeout,
 	}
 
+	// ErrBrowserOpenFailed represents an error when opening the browser for authentication fails.
 	ErrBrowserOpenFailed = &AuthenticationError{
 		Type:    "browser_open_failed",
 		Message: "Failed to open browser for authentication",
@@ -90,7 +109,7 @@ var (
 	}
 )
 
-// NewAuthenticationError creates a new authentication error with a cause
+// NewAuthenticationError creates a new authentication error with a cause based on a base error.
 func NewAuthenticationError(baseErr *AuthenticationError, cause error) *AuthenticationError {
 	return &AuthenticationError{
 		Type:    baseErr.Type,
@@ -100,21 +119,21 @@ func NewAuthenticationError(baseErr *AuthenticationError, cause error) *Authenti
 	}
 }
 
-// IsAuthenticationError checks if an error is an authentication error
+// IsAuthenticationError checks if an error is an authentication error.
 func IsAuthenticationError(err error) bool {
 	var authenticationError *AuthenticationError
 	ok := errors.As(err, &authenticationError)
 	return ok
 }
 
-// IsOAuthError checks if an error is an OAuth error
+// IsOAuthError checks if an error is an OAuth error.
 func IsOAuthError(err error) bool {
 	var oAuthError *OAuthError
 	ok := errors.As(err, &oAuthError)
 	return ok
 }
 
-// GetUserFriendlyMessage returns a user-friendly error message
+// GetUserFriendlyMessage returns a user-friendly error message based on the error type.
 func GetUserFriendlyMessage(err error) string {
 	switch {
 	case IsAuthenticationError(err):

internal/auth/claude/html_templates.go

@@ -1,6 +1,12 @@
+// Package claude provides authentication and token management functionality
+// for Anthropic's Claude AI services. It handles OAuth2 token storage, serialization,
+// and retrieval for maintaining authenticated sessions with the Claude API.
 package claude
 
-// LoginSuccessHtml is the template for the OAuth success page
+// LoginSuccessHtml is the HTML template displayed to users after successful OAuth authentication.
+// This template provides a user-friendly success page with options to close the window
+// or navigate to the Claude platform. It includes automatic window closing functionality
+// and keyboard accessibility features.
 const LoginSuccessHtml = `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -202,7 +208,9 @@ const LoginSuccessHtml = `<!DOCTYPE html>
 </body>
 </html>`
 
-// SetupNoticeHtml is the template for the setup notice section
+// SetupNoticeHtml is the HTML template for the setup notice section.
+// This template is embedded within the success page to inform users about
+// additional setup steps required to complete their Claude account configuration.
 const SetupNoticeHtml = `
         <div class="setup-notice">
             <h3>Additional Setup Required</h3>

internal/auth/claude/oauth_server.go

@@ -1,3 +1,6 @@
+// Package claude provides authentication and token management functionality
+// for Anthropic's Claude AI services. It handles OAuth2 token storage, serialization,
+// and retrieval for maintaining authenticated sessions with the Claude API.
 package claude
 
 import (
@@ -13,24 +16,45 @@ import (
 	log "github.com/sirupsen/logrus"
 )
 
-// OAuthServer handles the local HTTP server for OAuth callbacks
+// OAuthServer handles the local HTTP server for OAuth callbacks.
+// It listens for the authorization code response from the OAuth provider
+// and captures the necessary parameters to complete the authentication flow.
 type OAuthServer struct {
-	server     *http.Server
-	port       int
+	// server is the underlying HTTP server instance
+	server *http.Server
+	// port is the port number on which the server listens
+	port int
+	// resultChan is a channel for sending OAuth results
 	resultChan chan *OAuthResult
-	errorChan  chan error
-	mu         sync.Mutex
-	running    bool
+	// errorChan is a channel for sending OAuth errors
+	errorChan chan error
+	// mu is a mutex for protecting server state
+	mu sync.Mutex
+	// running indicates whether the server is currently running
+	running bool
 }
 
-// OAuthResult contains the result of the OAuth callback
+// OAuthResult contains the result of the OAuth callback.
+// It holds either the authorization code and state for successful authentication
+// or an error message if the authentication failed.
 type OAuthResult struct {
-	Code  string
+	// Code is the authorization code received from the OAuth provider
+	Code string
+	// State is the state parameter used to prevent CSRF attacks
 	State string
+	// Error contains any error message if the OAuth flow failed
 	Error string
 }
 
-// NewOAuthServer creates a new OAuth callback server
+// NewOAuthServer creates a new OAuth callback server.
+// It initializes the server with the specified port and creates channels
+// for handling OAuth results and errors.
+//
+// Parameters:
+//   - port: The port number on which the server should listen
+//
+// Returns:
+//   - *OAuthServer: A new OAuthServer instance
 func NewOAuthServer(port int) *OAuthServer {
 	return &OAuthServer{
 		port:       port,
@@ -39,8 +63,13 @@ func NewOAuthServer(port int) *OAuthServer {
 	}
 }
 
-// Start starts the OAuth callback server
-func (s *OAuthServer) Start(ctx context.Context) error {
+// Start starts the OAuth callback server.
+// It sets up the HTTP handlers for the callback and success endpoints,
+// and begins listening on the specified port.
+//
+// Returns:
+//   - error: An error if the server fails to start
+func (s *OAuthServer) Start() error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 
@@ -79,7 +108,14 @@ func (s *OAuthServer) Start(ctx context.Context) error {
 	return nil
 }
 
-// Stop gracefully stops the OAuth callback server
+// Stop gracefully stops the OAuth callback server.
+// It performs a graceful shutdown of the HTTP server with a timeout.
+//
+// Parameters:
+//   - ctx: The context for controlling the shutdown process
+//
+// Returns:
+//   - error: An error if the server fails to stop gracefully
 func (s *OAuthServer) Stop(ctx context.Context) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -101,7 +137,16 @@ func (s *OAuthServer) Stop(ctx context.Context) error {
 	return err
 }
 
-// WaitForCallback waits for the OAuth callback with a timeout
+// WaitForCallback waits for the OAuth callback with a timeout.
+// It blocks until either an OAuth result is received, an error occurs,
+// or the specified timeout is reached.
+//
+// Parameters:
+//   - timeout: The maximum time to wait for the callback
+//
+// Returns:
+//   - *OAuthResult: The OAuth result if successful
+//   - error: An error if the callback times out or an error occurs
 func (s *OAuthServer) WaitForCallback(timeout time.Duration) (*OAuthResult, error) {
 	select {
 	case result := <-s.resultChan:
@@ -113,7 +158,13 @@ func (s *OAuthServer) WaitForCallback(timeout time.Duration) (*OAuthResult, erro
 	}
 }
 
-// handleCallback handles the OAuth callback endpoint
+// handleCallback handles the OAuth callback endpoint.
+// It extracts the authorization code and state from the callback URL,
+// validates the parameters, and sends the result to the waiting channel.
+//
+// Parameters:
+//   - w: The HTTP response writer
+//   - r: The HTTP request
 func (s *OAuthServer) handleCallback(w http.ResponseWriter, r *http.Request) {
 	log.Debug("Received OAuth callback")
 
@@ -171,7 +222,12 @@ func (s *OAuthServer) handleCallback(w http.ResponseWriter, r *http.Request) {
 	http.Redirect(w, r, "/success", http.StatusFound)
 }
 
-// handleSuccess handles the success page endpoint
+// handleSuccess handles the success page endpoint.
+// It serves a user-friendly HTML page indicating that authentication was successful.
+//
+// Parameters:
+//   - w: The HTTP response writer
+//   - r: The HTTP request
 func (s *OAuthServer) handleSuccess(w http.ResponseWriter, r *http.Request) {
 	log.Debug("Serving success page")
 
@@ -195,7 +251,16 @@ func (s *OAuthServer) handleSuccess(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
-// generateSuccessHTML creates the HTML content for the success page
+// generateSuccessHTML creates the HTML content for the success page.
+// It customizes the page based on whether additional setup is required
+// and includes a link to the platform.
+//
+// Parameters:
+//   - setupRequired: Whether additional setup is required after authentication
+//   - platformURL: The URL to the platform for additional setup
+//
+// Returns:
+//   - string: The HTML content for the success page
 func (s *OAuthServer) generateSuccessHTML(setupRequired bool, platformURL string) string {
 	html := LoginSuccessHtml
 
@@ -213,7 +278,11 @@ func (s *OAuthServer) generateSuccessHTML(setupRequired bool, platformURL string
 	return html
 }
 
-// sendResult sends the OAuth result to the waiting channel
+// sendResult sends the OAuth result to the waiting channel.
+// It ensures that the result is sent without blocking the handler.
+//
+// Parameters:
+//   - result: The OAuth result to send
 func (s *OAuthServer) sendResult(result *OAuthResult) {
 	select {
 	case s.resultChan <- result:
@@ -223,7 +292,11 @@ func (s *OAuthServer) sendResult(result *OAuthResult) {
 	}
 }
 
-// isPortAvailable checks if the specified port is available
+// isPortAvailable checks if the specified port is available.
+// It attempts to listen on the port to determine availability.
+//
+// Returns:
+//   - bool: True if the port is available, false otherwise
 func (s *OAuthServer) isPortAvailable() bool {
 	addr := fmt.Sprintf(":%d", s.port)
 	listener, err := net.Listen("tcp", addr)
@@ -236,7 +309,10 @@ func (s *OAuthServer) isPortAvailable() bool {
 	return true
 }
 
-// IsRunning returns whether the server is currently running
+// IsRunning returns whether the server is currently running.
+//
+// Returns:
+//   - bool: True if the server is running, false otherwise
 func (s *OAuthServer) IsRunning() bool {
 	s.mu.Lock()
 	defer s.mu.Unlock()

internal/auth/claude/pkce.go

@@ -1,3 +1,6 @@
+// Package claude provides authentication and token management functionality
+// for Anthropic's Claude AI services. It handles OAuth2 token storage, serialization,
+// and retrieval for maintaining authenticated sessions with the Claude API.
 package claude
 
 import (
@@ -8,7 +11,13 @@ import (
 )
 
 // GeneratePKCECodes generates a PKCE code verifier and challenge pair
-// following RFC 7636 specifications for OAuth 2.0 PKCE extension
+// following RFC 7636 specifications for OAuth 2.0 PKCE extension.
+// This provides additional security for the OAuth flow by ensuring that
+// only the client that initiated the request can exchange the authorization code.
+//
+// Returns:
+//   - *PKCECodes: A struct containing the code verifier and challenge
+//   - error: An error if the generation fails, nil otherwise
 func GeneratePKCECodes() (*PKCECodes, error) {
 	// Generate code verifier: 43-128 characters, URL-safe
 	codeVerifier, err := generateCodeVerifier()

internal/auth/claude/token.go

@@ -1,3 +1,6 @@
+// Package claude provides authentication and token management functionality
+// for Anthropic's Claude AI services. It handles OAuth2 token storage, serialization,
+// and retrieval for maintaining authenticated sessions with the Claude API.
 package claude
 
 import (
@@ -7,32 +10,50 @@ import (
 	"path"
 )
 
-// ClaudeTokenStorage extends the existing GeminiTokenStorage for Anthropic-specific data
-// It maintains compatibility with the existing auth system while adding Anthropic-specific fields
+// ClaudeTokenStorage stores OAuth2 token information for Anthropic Claude API authentication.
+// It maintains compatibility with the existing auth system while adding Claude-specific fields
+// for managing access tokens, refresh tokens, and user account information.
 type ClaudeTokenStorage struct {
-	// IDToken is the JWT ID token containing user claims
+	// IDToken is the JWT ID token containing user claims and identity information.
 	IDToken string `json:"id_token"`
-	// AccessToken is the OAuth2 access token for API access
+
+	// AccessToken is the OAuth2 access token used for authenticating API requests.
 	AccessToken string `json:"access_token"`
-	// RefreshToken is used to obtain new access tokens
+
+	// RefreshToken is used to obtain new access tokens when the current one expires.
 	RefreshToken string `json:"refresh_token"`
-	// LastRefresh is the timestamp of the last token refresh
+
+	// LastRefresh is the timestamp of the last token refresh operation.
 	LastRefresh string `json:"last_refresh"`
-	// Email is the Anthropic account email
+
+	// Email is the Anthropic account email address associated with this token.
 	Email string `json:"email"`
-	// Type indicates the type (gemini, chatgpt, claude) of token storage.
+
+	// Type indicates the authentication provider type, always "claude" for this storage.
 	Type string `json:"type"`
-	// Expire is the timestamp of the token expire
+
+	// Expire is the timestamp when the current access token expires.
 	Expire string `json:"expired"`
 }
 
-// SaveTokenToFile serializes the token storage to a JSON file.
+// SaveTokenToFile serializes the Claude token storage to a JSON file.
+// This method creates the necessary directory structure and writes the token
+// data in JSON format to the specified file path for persistent storage.
+//
+// Parameters:
+//   - authFilePath: The full path where the token file should be saved
+//
+// Returns:
+//   - error: An error if the operation fails, nil otherwise
 func (ts *ClaudeTokenStorage) SaveTokenToFile(authFilePath string) error {
 	ts.Type = "claude"
+
+	// Create directory structure if it doesn't exist
 	if err := os.MkdirAll(path.Dir(authFilePath), 0700); err != nil {
 		return fmt.Errorf("failed to create directory: %v", err)
 	}
 
+	// Create the token file
 	f, err := os.Create(authFilePath)
 	if err != nil {
 		return fmt.Errorf("failed to create token file: %w", err)
@@ -41,9 +62,9 @@ func (ts *ClaudeTokenStorage) SaveTokenToFile(authFilePath string) error {
 		_ = f.Close()
 	}()
 
+	// Encode and write the token data as JSON
 	if err = json.NewEncoder(f).Encode(ts); err != nil {
 		return fmt.Errorf("failed to write token to file: %w", err)
 	}
 	return nil
-
 }