64 lines
3.5 KiB
Markdown
64 lines
3.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Core Design Principles
|
|
- **Principle of Least Surprise**: All UI behaviors should be predictable and intuitive
|
|
- **Dead Simple**: Complexity in storage, simplicity in interaction
|
|
- **Progressive Disclosure**: Basic operations stay simple, advanced features are optional
|
|
- **Backward Compatible**: Existing commands work unchanged on Default list
|
|
|
|
## Development Commands
|
|
|
|
- **Build project**: `cargo build`
|
|
- **Build release**: `cargo build --release`
|
|
- **Run locally**: `cargo run -- <subcommand> <args>` (e.g., `cargo run -- add "test item"`)
|
|
- **Run tests**: `cargo test`
|
|
- **Check code**: `cargo check`
|
|
- **Format code**: `cargo fmt`
|
|
- **Lint code**: `cargo clippy`
|
|
- **Install from source**: `cargo build --release && cp target/release/ldr ~/.local/bin/`
|
|
|
|
## Project Architecture
|
|
|
|
LDR is a Rust CLI productivity application implementing the "append-and-review" note system with Markdown format and subtask support. The architecture follows a clean separation of concerns:
|
|
|
|
### Core Structure
|
|
- **main.rs**: Entry point with CLI definition using `clap`. Handles XDG-compliant data directory setup (`~/.local/share/ldr/`) and automatic migration from plain text to Markdown format
|
|
- **commands.rs**: Command implementations with terminal I/O, file operations, and colored output using `termion`. Handles subtask operations and task reference parsing (1, 2a, 3b format)
|
|
- **markdown.rs**: Core data structures and parsing/generation for Markdown todo files. Supports single-level nesting (tasks with subtasks) and multiple named lists
|
|
- **migration.rs**: One-time migration utilities for converting plain text files to Markdown format with Default list structure
|
|
- **content.rs**: Legacy compatibility functions maintained for existing tests
|
|
- **input.rs**: Raw keyboard input handling for interactive review mode (currently simplified)
|
|
|
|
### File Format
|
|
- **todos.md**: Markdown file with multiple lists (Default list is primary)
|
|
- **archive.md**: Markdown archive with date-based sections and list organization
|
|
- **Migration**: Automatic one-time conversion from `note.txt`/`archive.txt` to Markdown format
|
|
|
|
### Task System
|
|
- **Task References**: Number+letter format (1, 2a, 3b) for referencing tasks and subtasks
|
|
- **Single-Level Nesting**: Tasks can have subtasks, but subtasks cannot have sub-subtasks
|
|
- **Default List**: Primary list for backward compatibility - all existing commands work on Default
|
|
- **Multiple Lists**: Support for named lists (Work, Personal, etc.) with `--list` flag
|
|
|
|
### Key Design Patterns
|
|
- **Markdown Storage**: Human-readable format with proper structure
|
|
- **Flat Numbering**: Simple number+letter system for task references
|
|
- **Backward Compatibility**: Existing interface unchanged, new features are additive
|
|
- **XDG Compliance**: Uses `xdg` crate for proper data directory handling
|
|
- **Migration on First Run**: Seamless upgrade from old format with backups
|
|
|
|
### Data Flow
|
|
1. CLI parsing extracts subcommands and arguments
|
|
2. Migration check and execution if needed (first run only)
|
|
3. XDG directories resolved for Markdown files (`todos.md`, `archive.md`)
|
|
4. Commands parse task references and delegate to Markdown operations
|
|
5. File I/O operations handle Markdown parsing/generation
|
|
6. Terminal output provides user feedback with colors and proper formatting
|
|
|
|
### Task Reference System
|
|
- **1**: Task 1 and all its subtasks
|
|
- **1a**: Only subtask 'a' of task 1
|
|
- **2b**: Only subtask 'b' of task 2
|
|
- Operations default to whole tasks, subtask references are specific |