From 9e3328a6aaefe4bd1aa0ec3e8bf6e93d6033180b Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Sun, 20 Jul 2025 21:20:40 +0300
Subject: test: add comprehensive test suite for audio and anki packages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add tests for audio package (62.8% coverage)
  - OpenAI provider tests with mocking
  - Provider interface and fallback mechanism tests
  - Bulgarian text validation tests
  - Audio caching functionality tests

- Add tests for anki package (84.8% coverage)
  - CSV generation tests
  - APKG package generation tests
  - Card management and formatting tests
  - Directory scanning and media handling tests

- Add test utilities and mocks
  - Mock implementations for external dependencies
  - Test helpers for common operations
  - Utilities for creating test directories and files

- Update Taskfile.yaml with comprehensive test targets
  - test: Run all tests
  - test-verbose: Run with verbose output
  - test-coverage: Run with coverage report
  - test-coverage-html: Generate HTML coverage report
  - test-race: Run with race detector
  - test-short: Run only short tests
  - test-all: Comprehensive suite with coverage and race detection
  - clean: Remove build artifacts and test files

- Fix existing image package tests
  - Remove tests for non-existent methods
  - Update tests to match actual implementation
  - Skip tests requiring live OpenAI API

This provides a solid foundation for ensuring code quality and catching regressions.

🤖 Generated with [opencode](https://opencode.ai)

Co-Authored-By: opencode <noreply@opencode.ai>
---
 AGENTS.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 AGENTS.md

(limited to 'AGENTS.md')

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..6ed9514
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,104 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+**totalrecall** - Bulgarian Anki Flashcard Generator
+
+A Go CLI tool that generates Anki flashcard materials from Bulgarian words:
+- Generates audio pronunciation using OpenAI TTS
+- Generates images using OpenAI DALL-E
+- Creates Anki-compatible output files
+
+## Important: Task Tracking
+**Always check TODO.md for the current implementation status and pending tasks.** The TODO.md file contains a comprehensive breakdown of all features and their completion status.
+
+## Build and Development Commands
+
+### Available Tasks (via Taskfile)
+```bash
+# Build the binary
+task
+# or
+task default
+
+# Run the application
+task run
+
+# Run tests
+task test
+
+# Install to Go bin directory
+task install
+```
+
+### Common Development Commands
+```bash
+# Build for current platform
+go build -o totalrecall ./cmd/totalrecall
+
+# Run without building
+go run ./cmd/totalrecall "ябълка"
+
+# Run tests with coverage
+go test -v -cover ./...
+
+# Check for race conditions
+go test -race ./...
+
+# Format code
+go fmt ./...
+
+# Lint code (requires golangci-lint)
+golangci-lint run
+```
+
+## Architecture Overview
+
+### Package Structure
+```
+totalrecall/
+├── cmd/totalrecall/          # CLI entry point
+├── internal/          # Private packages
+│   ├── audio/        # Audio generation (OpenAI TTS)
+│   ├── image/        # Image generation functionality
+│   ├── anki/         # Anki format generation
+│   ├── config/       # Configuration management
+│   └── version.go    # Version information
+```
+
+### Key Design Decisions
+1. **OpenAI TTS**: High-quality, natural-sounding Bulgarian pronunciation
+2. **Image generation**: Uses OpenAI DALL-E for AI-generated images
+3. **Configuration via YAML**: User-friendly configuration with viper
+4. **Cobra for CLI**: Industry-standard CLI framework
+
+### External Dependencies
+- **OpenAI API Key**: Required for both audio generation and image creation
+
+## Testing Approach
+1. Unit tests mock API calls
+2. Integration tests use real services when available
+3. Test with common Bulgarian words: ябълка, котка, куче, хляб
+
+## Common Issues and Solutions
+
+
+### Package Declaration Error
+If you see an error about `package main`, ensure `cmd/totalrecall/main.go` has:
+```go
+package main  // NOT package bulg
+```
+
+## Development Workflow
+1. Check TODO.md for next tasks
+2. Create feature branch
+3. Implement with tests
+4. Update documentation
+5. Run full test suite
+6. Submit for review
+
+## Bulgarian Language Notes
+- Input should be in Cyrillic script
+- Common test words: ябълка (apple), котка (cat), куче (dog)
+- OpenAI voices: nova, alloy, echo, shimmer (work well for Bulgarian)
-- 
cgit v1.2.3