my-log/AGENTS.md

Agent Guidelines for my-log

Build/Test/Lint Commands

• Build: make build or go build -o my-log
• Test all: make test (runs fmt + test with race + coverage)
• Test single: go test ./path/to/package -run TestName
• Format: make fmt or go fmt ./...
• Coverage report: make report (generates cover.html)

Code Style

• Module: codeberg.org/danjones000/my-log
• Go version: 1.21.5
• Imports: Standard library first, then external packages, then local packages. Use short aliases for common imports (e.g., fp for path/filepath, mapst for mitchellh/mapstructure)
• Formatting: Always run go fmt before commits (included in test target)
• Types: Use explicit types (e.g., int64, float64). Convert numbers appropriately when unmarshaling JSON
• Naming: PascalCase for exported, camelCase for unexported. Use descriptive names
• Error handling: Return wrapped errors with context. Define custom errors in models/errors.go. Use ErrorIs for error checking
• Testing: Use testify/assert. Table-driven tests with helper functions. Test both marshal/unmarshal for encoding types
• Concurrency: Use channels and goroutines with WaitGroups for parallel processing (see entry.go patterns)
• Comments: Include license header on cmd files. Document exported functions and types

Git Commit Guidelines

• Format: Prepend commit messages with a gitmoji emoji (see https://gitmoji.dev)
• Style: Write detailed commit messages that explain what changed and why
• Examples: ✨ Add JSON export functionality for log entries, 🐛 Fix date parsing for RFC3339 timestamps, 📝 Update README with configuration examples

Git Flow Workflow

• Main branches: stable (production-ready), develop (integration branch)
• Development: Always commit new features/fixes to develop branch or appropriate feature branches
• Branch prefixes:
  • feat/feature-name - New features, merge to develop when complete
  • bug/bug-name - Bug fixes (non-urgent), merge to develop when complete
  • hot/version - Hotfixes for production issues, merge to both stable and develop
  • rel/version - Release preparation branches
• Version tags: Prefix all version tags with v (e.g., v1.0.2, v0.0.6)
• Releases: Update CHANGELOG.md with a summary of changes for each new version
• Never commit directly to: stable branch (only merge from rel/ or hot/ branches)
• Before starting work: Ensure you're on develop branch or create an appropriate feature branch from it

Project Structure

• cmd/my-log/: Main application entrypoint
• internal/cmd/: Cobra commands (root, drop, config)
• models/: Core types (Entry, Log, Meta) with marshal/unmarshal implementations
• config/: TOML-based configuration with env overrides
• formatters/: Output formatters (plain, json, null)
• files/: File operations (append)
• tools/: Utilities (date parsing, string parsing, write buffers)