# Pen Tracker Project Documentation

## Overview

`pen-tracker` is a small Python package for tracking fountain pens and inks using CSV storage. It provides a single command-line interface (`pen-tracker`) for interactive data management, plus direct CLI commands for adding, listing, exporting, and maintaining the collection.

This repository is structured as a standard Python package with source under `src/pen_tracker`, package metadata in `pyproject.toml`, and a small test suite under `tests`.

## Key goals

- Maintain a pen collection with fields such as make, model, nib, ink, purchase date, and notes.
- Maintain an ink collection separately with vendor, name, color, purchase date, size, and notes.
- Store data in CSV files for compatibility and simplicity.
- Use a single CLI entry point for developer and automation workflows.

## Repository layout

- `pyproject.toml` — packaging metadata, dependencies, and entry points.
- `README.md` — user-facing usage documentation.
- `PROJECT_DOCUMENTATION.md` — developer/AI reference documentation.
- `import_csv_to_sqlite.py` — standalone CSV-to-SQLite migration helper.
- `src/pen_tracker/engine.py` — domain logic, data models, SQLite persistence, history tracking, and storage defaults.
- `src/pen_tracker/cli.py` — command-line interface, interactive menus, and command parsing.
- `tests/test_engine.py` — basic test coverage for core engine behavior.

## Core components

### `src/pen_tracker/engine.py`

Primary responsibilities:

- Define `Pen` and `Ink` dataclasses.
- Provide `PenTracker` and `InkTracker` classes that:
  - Decide storage path from environment or default XDG data directories.
  - Load CSV files into Python objects.
  - Normalize data on load.
  - Persist sorted CSV output.

Important details:

- Default pen storage path: `~/.local/share/pen-tracker/pens.csv`
- Default ink storage path: `~/.local/share/pen-tracker/inks.csv`
- Environment overrides:
  - `PEN_TRACKER_CSV` for pen storage.
  - `INK_TRACKER_CSV` for ink storage.
- `PenTracker.load_data()` maps CSV headers like `Date-Purchased` and `Current-Ink` to dataclass fields like `Date_Purchased` and `Current_Ink`.
- CSV headers are written using the original hyphenated naming convention.

### `src/pen_tracker/cli.py`

Primary responsibilities:

- Parse command-line arguments with `argparse`.
- Provide commands for:
  - `add` — add a new pen from CLI inputs.
  - `list` — display all pens.
  - `export` — export pens to JSON.
  - `add-ink` — add a new ink.
  - `list-inks` — list saved inks.
- Provide an interactive text menu when no command is supplied.
- Display one-based IDs for pens and inks.
- Validate user input and dates.

## Usage patterns

### Installation

```bash
pip install .
```

### Run interactive CLI

```bash
pen-tracker
```

### Add a pen via CLI

```bash
pen-tracker add --make "Pilot" --model "Metropolitan" --nib "F"
```

### List saved pens

```bash
pen-tracker list
```

### Export pens to JSON

```bash
pen-tracker export --output my_pens.json
```

### Add an ink via CLI

```bash
pen-tracker add-ink --vendor "Diamine" --name "Majestic Blue" --color "Blue"
```

### List inks

```bash
pen-tracker list-inks
```

## Data model

### Pen fields

- `Make`
- `Model`
- `Date_Purchased` / `Date-Purchased`
- `Vendor`
- `Nib`
- `Nib_Material` / `Nib-Material`
- `Body`
- `Cap`
- `Post`
- `Current_Ink` / `Current-Ink`
- `Inked_date` / `Inked-date`
- `Notes`

### Ink fields

- `Vendor`
- `Name`
- `Color`
- `Purchased`
- `Size`
- `Notes`

## Packaging and scripts

The package is configured with `pyproject.toml` and uses `setuptools.build_meta` as the build backend. There are no runtime dependencies.

Entry point:

- `pen-tracker = pen_tracker.cli:main`

## Developer notes

- The CLI is the only supported interface. The repository no longer includes any TUI or graphical code.
- Data is now persisted in SQLite, with default path `~/.local/share/pen-tracker/pen_tracker.db`.
- Ink changes for each pen are recorded in `pen_ink_history`, including transitions to `N/A`.
- When modifying storage columns, update both `engine.py` and `cli.py` to maintain field mappings and database behavior.
- One-based IDs are used consistently for user-facing selection and display.
- SQLite persistence always sorts data before saving.

## Testing

- `tests/test_engine.py` contains test coverage for the core engine layer.
- Add tests for new fields, storage behavior, and CLI data validation if extending features.

## Notes for AI agents

- Focus on `src/pen_tracker/engine.py` for the data model and persistence logic.
- Focus on `src/pen_tracker/cli.py` for user-facing behavior, commands, and interactive menu flow.
- The default storage paths are derived from XDG conventions and environment variables.
- There is no GUI, web service, or database; all data is stored in CSV files.
- The project version is `0.5.0` and the package name is `pen-tracker`.

## Extension suggestions

- Add unit tests for the CLI parser and interactive menu flows.
- Add a dedicated `docs/` folder if more formal design docs or API references are needed.
- Add JSON schema validation or stronger date handling if data robustness is required.