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 has dual entry points: hello (hello_world package) and taco (trygo_py_cliclient.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

Architecture

Package Structure

• src/hello_world/ - Hello world demonstration package
• src/trygo_py_cliclient/ - Main CLI client package
  • cli/ - Command-line interface and argument parsing
  • config/ - Configuration management with TOML support

Configuration System

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

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

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

Entry Points

• hello command maps to hello_world:main
• taco command maps to trygo_py_cliclient.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