# `main.rs` – Binary Entry Point

## Purpose
`main.rs` is the **executable entry point** for the Todozi command‑line application.
It wires together:

* **Argument parsing** – using `clap` to interpret sub‑commands such as `add`, `list`, `search`, `server`, etc.
* **Storage initialization** – creates the `~/.todozi/` directory hierarchy on first run.
* **Command dispatch** – instantiates a `TodoziHandler` (which owns a `Storage`) and forwards the parsed command to the appropriate asynchronous handler (`handle_api_command`, `handle_queue_command`, `handle_server_command`).

The file also conditionally enables the **terminal UI** (`tui`) when compiled with the `tui` feature flag.

---

## High‑Level Flow (Mermaid)

```mermaid
flowchart TD
    A[Program start] --> B[Parse CLI args (clap)]
    B --> C{Command group?}
    C -->|api| D[handler.handle_api_command]
    C -->|queue| E[handler.handle_queue_command]
    C -->|server| F[handler.handle_server_command]
    C -->|task| G[Sync helpers (add, delete, complete, …)]
    D --> H[Print human‑readable output]
    E --> H
    F --> H
    G --> H
    H --> I[Exit with status code]
```

1. **Parse** – `clap::Parser::parse()` builds a `Cli` enum representing the chosen sub‑command.
2. **Init storage** – `Storage::new()` creates `~/.todozi/` if it does not exist and runs any pending migrations.
3. **Instantiate handler** – `TodoziHandler::new(storage)` bundles the storage for later calls.
4. **Dispatch** – The `match` on the `Cli` variant calls the corresponding async method on the handler.
5. **Result handling** – Errors are printed to `stderr`; a non‑zero exit code signals failure.

---

## Key Types & Functions

| Type / Function | Description |
|-----------------|-------------|
| `TodoziHandler` | Holds a `Storage` and provides both synchronous helpers (`complete_task`, `delete_task`, …) and async dispatchers for API, queue, and server commands. |
| `Storage` | Low‑level file‑based persistence layer (`~/.todozi/`); implements CRUD for tasks, projects, agents, memories, etc. |
| `Cli` (in `src/types.rs`) | Enum of all top‑level commands and their arguments (e.g., `Add(AddArgs)`, `List(ListArgs)`). |
| `run()` (async) | Entry point for the Tokio runtime; creates the handler and executes the matched command. |
| `main()` | Starts the Tokio runtime (`tokio::main`) and awaits `run()`. |
| `#[cfg(feature = "tui")]` | Conditional compilation block that launches the TUI (`TuiService::run()`) instead of the plain CLI when the `tui` feature is enabled. |

---

## Example Invocation

```sh
# Initialise a fresh workspace (creates ~/.todozi/)
todozi init

# Add a new high‑priority task to project "backend"
todozi add task "Implement OAuth login" \
    --time "2h" \
    --priority high \
    --project backend

# Start the server on a custom host/port
todozi server start --host 0.0.0.0 --port 8636

# Launch the interactive terminal UI (if compiled with `tui`)
todozi tui
```

Each command ultimately flows back to `main.rs`, which creates or re‑uses the same `Storage` instance, ensuring a **single source of truth** for all persisted data.

---

## Extending `main.rs`

When adding a new top‑level command:

1. **Update `src/types.rs`** – Add a new variant to the `Cli` enum with its argument struct.
2. **Add a match arm** – In `run()`, handle the new variant and call a method on `TodoziHandler` (or a new dispatcher).
3. **Document** – Add the command description to `docs/cmd.md` and create a dedicated `*_lib.md` file if needed.

---

## Testing

`src/tests.rs` contains integration tests that invoke the `run()` function directly with mock arguments, avoiding a full process spawn. Typical pattern:

```rust
#[tokio::test]
async fn test_add_task() {
    // Simulate `todozi add task "Test" --time "1h" --priority low --project demo`
    let args = vec!["todozi", "add", "task", "Test", "--time", "1h", "--priority", "low", "--project", "demo"];
    let cli = Cli::parse_from(args);
    // Run the command via the same path as `run()` does
    // Assert that the task file now exists under ~/.todozi/tasks/demo/
}
```

---

## Related Files

| File | Role |
|------|------|
| `src/cli.rs` | Contains `TodoziHandler` methods that actually perform the work for each command. |
| `src/types.rs` | Defines the `Cli` enum and argument structs parsed by `clap`. |
| `src/storage.rs` | Implements the persistent storage accessed by the handler. |
| `src/tui.rs` | Provides the optional terminal UI launched from `main.rs` when the `tui` feature is enabled. |
| `src/server.rs` | Implements the async server started by the `server` sub‑command. |

---

*Generated by GPT‑OSS – documentation for the binary entry point (`main.rs`).*
