adding upload testing, etc.

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## 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 has dual entry points: `hello` (hello_world package) and `taco` (trygo_py_cliclient.cli package).
+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
 
@@ -21,19 +21,107 @@ This is a Python CLI client for the trygo webapp built with a hybrid development
 - `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/trygo_py_cliclient/` - Main CLI client 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/trygo_py_cliclient/config/config.py`)
+- 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
@@ -44,6 +132,7 @@ The project supports both uv and Nix environments:
 - 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)
@@ -51,9 +140,42 @@ The project supports both uv and Nix environments:
 - 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`
-- `taco` command maps to `trygo_py_cliclient.cli:main`
+- `taiga` command maps to `taiga_pycli.cli:main`
 
 ## Configuration Files
 - `pyproject.toml` - Python project configuration and dependencies