Metadata-Version: 2.5
Name: farora
Version: 0.5.0
Summary: A local-first, plain-text task tracker with a Textual TUI.
Project-URL: Homepage, https://farora.tools
Author-email: Dmytro Shandyba <hi@farora.tools>
License-Expression: LicenseRef-Farora-1.0
License-File: LICENSE
Keywords: cli,local-first,markdown,plain-text,task-tracker,textual,todo,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Utilities
Requires-Python: >=3.14
Requires-Dist: fractional-indexing<0.2,>=0.1.3
Requires-Dist: pydantic<3,>=2.13
Requires-Dist: rich>=14.2
Requires-Dist: textual<9,>=8.2
Requires-Dist: tomli-w>=1.1
Requires-Dist: watchfiles<2,>=1.2
Description-Content-Type: text/markdown

# Farora

A local-first, plain-text task tracker with a Textual TUI.

Tasks live as Markdown files with YAML frontmatter in a plain folder, so they
sync over any file-sync engine, diff cleanly in git, and stay readable without
Farora.

## Install

```sh
uvx farora                 # run without installing
uv tool install farora     # install persistently
```

If your `uv` is older and picks an interpreter below 3.14, name one explicitly:

```sh
uv tool install --python 3.14 farora
```

## Supported configuration

Farora 0.5 is developed and tested on **macOS with Python 3.14+**. `uv` provisions
the interpreter for you.

These tools are optional — each unlocks a feature, and Farora degrades cleanly
without it:

| Tool | Unlocks |
|---|---|
| [helix](https://helix-editor.com/) | `e` opens the task body in helix (otherwise `$EDITOR`, then `vi`) |
| [mdcat](https://github.com/swsnr/mdcat) ≥ 2.11 | `v` / `V` live markdown render with inline images |
| [WezTerm](https://wezterm.org/) | `v` renders side by side in a split pane |
| git ≥ 2.30 | Sync a task repo across machines |

Linux and Windows are not supported in this release.

## Commands

| Command | Purpose |
|---|---|
| `farora` | launch the TUI |
| `farora doctor` | validate and reconcile a repo |
| `farora gc [--older-than DURATION]` | purge expired tombstones now |

All commands accept `--repo PATH`, defaulting to `$FARORA_REPO`, else `~/.farora`.

## Deleted tasks are kept before they are gone

Deleting a task removes its `tasks/FAR-42.md`, but its journal stays behind as a
**tombstone** holding a full snapshot of the task — frontmatter *and* body text. That
is what `u` undoes a delete from, and what a future `farora restore` would rebuild
from.

**So a deleted task's text is still readable in the repo, in
`projects/FAR/journal/FAR-42.jsonl`, until garbage collection removes it.** If a task
held something sensitive, deleting it is not the same as shredding it — anything
syncing or backing up the folder has the snapshot too.

Garbage collection runs **opportunistically**: every ordinary `farora` run sweeps the
repo it opens, so there is no daemon and nothing to schedule. Tombstones older than the
retention window are purged; everything else — every live task, and every tombstone
still inside the window — is left alone.

```sh
farora gc                      # purge now, using the configured window
farora gc --older-than 0s      # purge every tombstone, right now
farora gc --older-than 7d      # ... or everything deleted over a week ago
```

Configure it in `~/.config/farora/config.toml`:

```toml
[gc]
enabled   = true    # false: never sweep on ordinary runs (`farora gc` still works)
retention = "30d"   # how long a deleted task's snapshot is kept: s | m | h | d | w
```

Both keys are optional and the values above are the defaults. Purging is permanent:
once a tombstone is collected, undo and restore have nothing to work from, and the task
number is never reused.

## License

Proprietary. See LICENSE.

**Free to use for any purpose, including commercially** — by individuals and by
companies, at no charge and without asking. Redistribution and modification are not
permitted.

To license Farora on other terms, contact <hi@farora.tools>.
