trygo-py-cliclient/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Python CLI client for the TryGo webapp built with a hybrid development environment using both uv and Nix. The project provides a complete CLI interface for the TryGo Activity Files API, allowing users to upload, manage, and interact with activity files (.fit files). The project has dual entry points: hello (hello_world package) and taiga (taiga_pycli.cli package).

Development Commands

Core Commands (via justfile)

• just test - Run full test suite (ruff check + mypy + pytest)
• just fmt - Format code using nix fmt (includes ruff, nixfmt, etc.)
• just update-snapshots - Update test snapshots using syrupy
• just build - Build the Python module (currently placeholder)
• just check - Run nix flake check for Nix environment validation

Direct Tool Commands

• uv run pytest - Run tests with coverage
• uv run ruff check src tests - Lint code
• uv run mypy src - Type checking
• uv run pytest --snapshot-update - Update test snapshots

CLI Commands

The taiga CLI provides the following commands:

Authentication Commands

• taiga register --email <email> --password <password> --display-name <name> - Register new user account
• taiga login --email <email> --password <password> - Authenticate and store JWT token

Activity File Commands

• taiga activities upload <file_path> - Upload activity files (.fit files) to the server
  • Requires authentication (login first)
  • Validates file existence and readability
  • Uses current timestamp automatically
  • Returns activity file metadata on success
• taiga activities ls - List all activity files for the authenticated user
  • Shows ID, timestamp, and creation date in tabular format
  • Requires authentication (login first)
• taiga activities download <id> [--output <path>] - Download activity file by ID
  • Downloads activity file to specified path or defaults to activity_{id}.fit
  • Requires authentication (login first)

Other Commands

• taiga hat - Hat management commands (development/testing feature)

Examples

# Register and login
taiga register --email "user@example.com" --password "mypassword" --display-name "My Name"
taiga login --email "user@example.com" --password "mypassword"

# Activity file management
taiga activities upload activity.fit
taiga activities upload local/test-data/test.fit
taiga activities ls
taiga activities download 1
taiga activities download 1 --output my_activity.fit

Architecture

Package Structure

• src/hello_world/ - Hello world demonstration package
• src/taiga_pycli/ - Main CLI client package
  • cli/ - Command-line interface and argument parsing
  • config/ - Configuration management with TOML support
  • service/ - Backend API service layer
  • models.py - Data models for API requests/responses

Upload Functionality

The upload feature provides seamless integration with the TryGo Activity Files API:

Implementation Details

• ActivityFile Model: Dataclass representing activity file metadata with fields for id, timestamp, file_repo_hash, created_at, updated_at, and user_id
• BackendService.upload_activity_file(): Handles multipart file uploads with proper JWT authentication
• File Validation: Checks file existence, readability, and path validity before upload
• Error Handling: Comprehensive error handling for authentication, validation, network, and server errors
• Automatic Timestamping: Uses current time for activity timestamp (no custom timestamp needed)

Supported File Formats

• Primary: .fit files (Garmin activity files)
• The API accepts any file format, but the CLI is designed for activity files

Authentication Requirements

• Must be logged in with valid JWT token before uploading
• Token is automatically stored in cred/token after login
• Token is automatically included in upload requests

Error Scenarios Handled

• File not found or not readable
• Not authenticated (missing/invalid token)
• Network connectivity issues
• Server errors (400, 500, etc.)
• Invalid API responses

Configuration System

• Uses dataclasses for type-safe configuration (src/taiga_pycli/config/config.py)
• TOML-based configuration files (config.toml)
• Supports logging configuration and general application settings

TryGo Activity Files API Integration

• BackendService Class: Centralized API client with session management

  • JWT token authentication with automatic header injection
  • Token persistence in cred/token file
  • Comprehensive error handling with custom exception types
  • Support for authentication endpoints (/auth/register, /auth/tokens)
  • Support for activity file endpoints (/activity_files, /activity_files/{id}/download)
  • Methods: upload_activity_file(), list_activity_files(), download_activity_file()

• Data Models: Type-safe dataclasses for API interactions

  • ActivityFile: Response model for activity file metadata
  • RegisterRequest/LoginRequest: Authentication request models
  • AuthResponse: Authentication response model

• Error Handling Strategy: Custom exception hierarchy

  • AuthenticationError: 401 responses and missing tokens
  • ValidationError: 400 responses and file validation issues
  • NetworkError: Connection timeouts and network issues
  • ServerError: 5xx server responses
  • TryGoAPIError: General API errors

Development Environment

The project supports both uv and Nix environments:

• uv mode: Standard Python toolchain with uv for dependency management
• Nix mode: Reproducible environment with integrated formatting tools
• Environment detection via DO_NIX_CUSTOM environment variable

Testing

• pytest with syrupy for snapshot testing
• Coverage reporting enabled (50% minimum)
• Test configuration in pyproject.toml with XML and HTML output
• Custom testing scripts for upload functionality validation

Code Quality

• ruff for linting and formatting (tab indentation style)
• mypy for type checking
• flake8 for additional linting
• treefmt.nix for comprehensive formatting in Nix environment

Testing and Development Scripts

Development Scripts

• scripts/simple_create_user.sh - Quick user registration script for testing

  • Creates test user with email "test@example.com" and password "test"
  • Used for development and testing workflows

• scripts/test_upload.sh - Comprehensive upload functionality testing

  • Tests authentication requirements (upload without login should fail)
  • Tests successful login workflow
  • Tests successful file upload
  • Tests error handling (non-existent files)
  • Provides complete end-to-end validation

Test Data

• local/test-data/ - Directory containing real .fit files for testing
  • test.fit, test2.fit, test3.fit - Sample activity files
  • Organized separately from development files
  • Used by test scripts for realistic upload testing

Testing Workflow

# Run complete upload test suite
./scripts/test_upload.sh

# Manual testing steps
./scripts/simple_create_user.sh  # Create test user (if needed)
taiga login --email "test@example.com" --password "test"
taiga activities upload local/test-data/test.fit
taiga activities ls
taiga activities download 1

Entry Points

• hello command maps to hello_world:main
• taiga command maps to taiga_pycli.cli:main

Configuration Files

• pyproject.toml - Python project configuration and dependencies
• config.toml - Application runtime configuration
• flake.nix - Nix development environment
• treefmt.nix - Code formatting configuration
• justfile - Development task automation