# TODO App — TypeScript CLI Project Specification

## Overview

A command-line TODO list manager written in TypeScript.
The app stores tasks in a local JSON file and supports full CRUD operations.

This project is designed to be **automatically generated, built, and tested**
by the proxym AI tool orchestration system.

## Functional Requirements

### Data Model

```typescript
interface Todo {
  id: string;          // UUID v4
  title: string;       // 1-255 chars
  description: string; // optional, max 1000 chars
  done: boolean;       // default: false
  priority: 'low' | 'medium' | 'high';  // default: 'medium'
  createdAt: string;   // ISO 8601
  updatedAt: string;   // ISO 8601
}
```

### CLI Commands

| Command | Description | Example |
|---------|-------------|---------|
| `todo add <title>` | Create a new task | `todo add "Buy milk" --priority high` |
| `todo list` | List all tasks | `todo list --filter done` |
| `todo show <id>` | Show task details | `todo show abc123` |
| `todo done <id>` | Mark task as done | `todo done abc123` |
| `todo undone <id>` | Mark task as not done | `todo undone abc123` |
| `todo edit <id>` | Edit task fields | `todo edit abc123 --title "New title"` |
| `todo remove <id>` | Delete a task | `todo remove abc123` |
| `todo stats` | Show statistics | `todo stats` |
| `todo clear` | Remove all done tasks | `todo clear --yes` |

### Storage

- JSON file at `~/.todo-app/todos.json` (configurable via `TODO_FILE` env var)
- Auto-create directory and file on first use
- Atomic writes (write to temp file, then rename)

### Output Format

- Colored terminal output (green for done, yellow for in-progress)
- Table format for `list` command
- Short ID display (first 8 chars of UUID)

## Technical Stack

| Component | Technology |
|-----------|------------|
| Language | TypeScript 5.x |
| Runtime | Node.js >= 18 |
| CLI framework | Commander.js |
| UUID generation | `crypto.randomUUID()` (built-in) |
| Testing | Vitest |
| Build | `tsc` (TypeScript compiler) |
| Linting | ESLint with `@typescript-eslint` |

## Project Structure

```
todo-app-ts/
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── src/
│   ├── index.ts          # CLI entry point (commander setup)
│   ├── types.ts          # Todo interface and enums
│   ├── store.ts          # JSON file storage (CRUD)
│   ├── commands.ts       # Command handlers
│   └── format.ts         # Output formatting helpers
├── tests/
│   ├── store.test.ts     # Unit tests for store
│   ├── commands.test.ts  # Unit tests for commands
│   └── cli.test.ts       # Integration tests (CLI invocation)
└── README.md
```

## Non-Functional Requirements

- All code must compile without errors (`tsc --noEmit`)
- Tests must pass (`npx vitest run`)
- No runtime dependencies beyond Commander.js
- Must work offline (no network calls)
- Exit codes: 0 = success, 1 = error, 2 = not found

## Acceptance Criteria

1. `npm install` completes without errors
2. `npm run build` produces JavaScript output in `dist/`
3. `npm test` runs all tests and they pass
4. `node dist/index.js add "Test task"` creates a task
5. `node dist/index.js list` shows the created task
6. `node dist/index.js done <id>` marks it as done
7. `node dist/index.js remove <id>` deletes it
8. `node dist/index.js stats` shows correct counts