FitTrack_GarminSync/specs/006-cli-auth-sync-mfa/plan.md

Implementation Plan: CLI App for API Interaction with MFA

Branch: 006-cli-auth-sync-mfa | Date: Thursday, December 18, 2025 | Spec: /home/sstent/Projects/FitTrack/GarminSync/specs/006-cli-auth-sync-mfa/spec.md Input: User description: "create a simple python CLI app for interacting with our API to authenticate the user, trigger a sync, and see the sync status. Allow for the use of MFA on the acct."

Summary

This feature implements a text-based command-line interface that allows users to authenticate with the API (with MFA support), trigger sync operations, and check sync status. The implementation follows the project's constitution standards, using Python 3.13 with appropriate libraries for CLI interface, authentication, and API communication.

Technical Context

Language/Version: Python 3.13 (Constitution requirement: Python Modernization principle)
Primary Dependencies: Click/Typer for CLI (Constitution requirement: cli_interface standard), httpx for API calls, pydantic for data validation, garth/garminconnect for Garmin authentication
Storage: Local file storage for authentication tokens and configuration (JSON/YAML format)
Testing: pytest (Constitution requirement: TDD principle) for unit and integration tests
Target Platform: Linux, macOS, Windows command-line environments
Project Type: Single project CLI application
Performance Goals: Authentication in under 30 seconds (per spec SC-001), status checks in under 5 seconds (per spec SC-003)
Constraints: Secure handling of credentials and tokens, support for MFA flows, offline token storage
Scale/Scope: Individual user tool, single-user operation, designed for personal use scenarios

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• Python Modernization: Compliant (Python 3.13, type hints, dataclasses for models)
• Virtual Environment Isolation: Compliant (uses .venv, dependencies will be pinned)
• Test-Driven Development: Compliant (pytest for testing, will follow TDD approach)
• Containerization Standards: Not applicable (CLI tool, not a containerized service)
• Project Structure Standards: Compliant (follows src/ structure with models, services, etc.)
• Service-Specific Standards:
  • cli_interface: Compliant (using Click as required by constitution, YAML config, multiple output formats)
• API Standards: Compliant (will interact with existing API endpoints following REST patterns)
• Code Quality Standards: Compliant (will use Black, Flake8, Mypy, Isort as required)
• Dependency Management: Compliant (will use requirements.txt with pinned dependencies)

All constitution gates pass. No violations detected post-design.

Project Structure

Documentation (this feature)

specs/006-cli-auth-sync-mfa/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)

Source Code (repository root)

cli/
├── src/
│   ├── __init__.py
│   ├── main.py              # CLI entry point with commands for auth, sync, status
│   ├── auth/
│   │   ├── __init__.py
│   │   ├── auth_manager.py  # Handles authentication flows with MFA support
│   │   └── token_manager.py # Manages local token storage and refresh
│   ├── api/
│   │   ├── __init__.py
│   │   ├── client.py        # API client for communicating with backend
│   │   └── endpoints.py     # API endpoint definitions
│   ├── models/
│   │   ├── __init__.py
│   │   ├── session.py       # User session data model
│   │   ├── sync_job.py      # Sync job data model
│   │   └── token.py         # Authentication token model
│   ├── commands/
│   │   ├── __init__.py
│   │   ├── auth_cmd.py      # Authentication command implementation
│   │   ├── sync_cmd.py      # Sync triggering command implementation
│   │   └── status_cmd.py    # Status checking command implementation
│   └── utils/
│       ├── __init__.py
│       ├── config.py        # Configuration handling
│       ├── output.py        # Output formatting (JSON, table, CSV)
│       └── validators.py    # Input validation utilities
├── tests/
│   ├── unit/
│   │   ├── test_auth_manager.py
│   │   ├── test_token_manager.py
│   │   ├── test_api_client.py
│   │   └── test_commands.py
│   ├── integration/
│   │   ├── test_auth_flow.py
│   │   └── test_sync_operations.py
│   └── contract/
│       └── test_api_contracts.py
└── requirements.txt

Structure Decision: Created a dedicated CLI directory with a modular structure following the constitution's source structure requirements. The CLI module will follow the cli_interface standards from the constitution, using Click/Typer for the interface and supporting configuration and output formats as required.

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because
(None)	(None)	(None)