Skip to content

CLAUDE.md

Latest commit

 

History

History
212 lines (160 loc) · 5.25 KB

CLAUDE.md

File metadata and controls

212 lines (160 loc) · 5.25 KB
Raw

Claude Code Guide for Track

This document provides context and guidelines for AI assistants working on the Track project. For complete contributing guidelines, see CONTRIBUTING.md.

Project Overview

Track is a command-line task management tool written in Rust that helps developers manage todos, links, and notes directly from the terminal. It features:

  • CLI Interface: Fast, intuitive command-line operations
  • Web UI: Browser-based interface with real-time updates
  • Database: SQLite for persistent storage
  • Shell Integration: Completions for bash/zsh/fish

Technology Stack

  • Language: Rust (stable)
  • CLI Framework: clap for argument parsing
  • Database: rusqlite for SQLite operations
  • Web Framework: axum for HTTP server
  • Frontend: HTMX + Vanilla JavaScript (no frameworks)
  • Real-time: Server-Sent Events (SSE) for live updates

Project Structure

track/
├── src/
│   ├── main.rs           # Binary entry (uses lib crate)
│   ├── lib.rs            # Library exports
│   ├── cli/              # Clap definitions + CommandHandler
│   ├── db/               # SQLite + row_mapping helpers
│   ├── models/           # Domain types (TaskStatus, TodoStatus, …)
│   ├── services/         # Task/Todo/Link/Repo/Worktree services
│   ├── use_cases/        # CompleteTodo, CreateTodayTask workflows
│   ├── utils/            # TrackError, Result
│   └── webui/            # Axum server, SSE, templates
├── templates/            # HTMX HTML (base.html, partials/)
├── static/               # Static assets
├── tests/                # Integration tests
└── CONTRIBUTING.md

See PROJECT_STRUCTURE.md for architecture details.

Key Development Commands

Before making any changes, always:

  1. Format code: cargo fmt
  2. Run linter: cargo clippy -- -D warnings
  3. Run tests: cargo test
  4. Build project: cargo build

Code Quality Requirements

All changes must pass:

  • ✅ cargo fmt (no formatting issues)
  • ✅ cargo clippy -- -D warnings (no warnings)
  • ✅ cargo test (all tests passing)

Common Patterns

Error Handling

use crate::TrackError;

fn operation() -> Result<T, TrackError> {
    let result = fallible_operation()?;
    Ok(result)
}

Database Operations

// Use parameterized queries
conn.execute(
    "INSERT INTO todos (description) VALUES (?1)",
    params![description],
)?;

CLI Commands

// Commands are in src/commands/
pub fn handle_command(args: &Args) -> Result<()> {
    // Implementation
}

Testing Guidelines

Unit Tests

Place tests in the same file:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_feature() {
        // Arrange, Act, Assert
    }
}

Integration Tests

Place in tests/ directory for end-to-end workflows.

Manual Testing

# Test CLI commands
cargo run -- todo add "Test task"
cargo run -- todo list

# Test WebUI
cargo run -- webui
# Open http://localhost:3000

WebUI Development

When working on the WebUI:

  1. Backend routes: Edit src/webui/routes.rs
  2. Templates: Edit files in templates/
  3. Styling: Modify CSS in templates/base.html
  4. Real-time updates: SSE state in src/webui/state.rs

Restart the server after changes:

cargo run -- webui

Coding Standards

Follow Rust conventions:

  • snake_case for functions, variables, modules
  • PascalCase for types and traits
  • SCREAMING_SNAKE_CASE for constants

See CONTRIBUTING.md for complete style guide.

Commit Message Format

<type>: <short summary>

<detailed description>

Types: feat, fix, docs, style, refactor, test, chore

Example:

feat: add priority field to todos

Added priority field (1-5) to todo items with database migration.
Updated CLI commands and WebUI to support priority filtering.

Before Submitting Changes

Checklist:

  • Read relevant code before modifying
  • Run cargo fmt
  • Run cargo clippy -- -D warnings (must pass)
  • Run cargo test (all tests pass)
  • Add tests for new features
  • Update documentation if needed
  • Follow commit message format
  • Verify manual testing for UI changes

Important Notes

  • Always read files before editing: Never propose changes to code you haven't read
  • Follow existing patterns: Check similar code in the codebase for consistency
  • Keep it simple: Avoid over-engineering, only make necessary changes
  • Test thoroughly: Both automated tests and manual verification
  • Security: Prevent SQL injection, XSS, and other vulnerabilities

Getting Help

  • Review CONTRIBUTING.md for detailed guidelines
  • Check existing code for patterns and examples
  • Look at recent commits for style reference
  • Test changes locally before submitting

Quick Reference

# Build and test
cargo build
cargo test
cargo fmt
cargo clippy -- -D warnings

# Run CLI
cargo run -- <command>

# Run WebUI
cargo run -- webui

# Run specific test
cargo test test_name

# View test output
cargo test -- --nocapture

For complete details, see CONTRIBUTING.md.