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
```bash
# 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
```bash
# 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