# torlinkc

A from-scratch C++ rewrite of torlink (npm package `torlnk`), a
terminal-native torrent finder and downloader. The engine is
[libtorrent-rasterbar](https://www.libtorrent.org/); the TUI is
[FTXUI](https://github.com/ArthurSonzogni/FTXUI).

This is a rewrite in progress, built phase by phase. See
[Status](#status) below for what currently works.

## Status

| Phase | What it delivers | Status |
| --- | --- | --- |
| 0 | Toolchain proof: libtorrent + FTXUI hello-worlds | ✅ done |
| 1 | Core download engine, persistence, bootguard, one source (apibay) | ✅ done |
| 2 | Minimal interactive FTXUI shell (search, download, live progress) | ✅ done |
| 3 | Full search parity across all 10 sources, real cancellation | ✅ done |
| 4 | Full TUI navigation: sidebar, Downloads/Seeding, prompts, help, splash | ✅ done |
| 5 | Headless daemon modes: `watch`/`serve`/`files`/`attach` | ⏳ not started |
| 6 | Self-update strategy, packaging, polish | ⏳ not started |

Linux and macOS are the target; Windows is explicitly deferred (no
`daemonize`/`attach` equivalent exists there).

A few pieces present in the original TypeScript app are deliberately out of
scope for now rather than silently dropped: clipboard paste/copy, exporting
a `.torrent` file from a search result, the animated progress-bar "sheen",
and pixel-exact layout spacing. These can follow once the phases above land.

## Building

### Dependencies

On Debian/Ubuntu, everything needed ships as a distro package (no vcpkg
bootstrap required):

```sh
sudo apt-get install -y \
  cmake build-essential pkgconf \
  libtorrent-rasterbar-dev libftxui-dev \
  libboost-system-dev libssl-dev \
  libcurl4-openssl-dev nlohmann-json3-dev doctest-dev
```

On macOS (via Homebrew), the equivalent packages are `cmake`,
`libtorrent-rasterbar`, `ftxui`, `curl`, `nlohmann-json`, and `doctest`
(some of these may need `brew install --HEAD` or a tap if not yet in
core — this path is untested so far).

### Build

```sh
cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build -j"$(nproc)"
```

This builds three programs plus the test suite:

- `build/apps/tui/torlinkc_tui` — the interactive terminal UI
- `build/apps/core_cli/torlinkc_core_cli` — a headless console harness
  (`search <query>` / `run [magnet|infohash] [dir]`), mainly useful for
  exercising the engine without a real terminal
- `build/phase0/{libtorrent_hello,ftxui_hello}` — the Phase 0 toolchain
  smoke tests
- `build/tests/torlinkc_tests` — the doctest suite

### Install (optional)

```sh
sudo cmake --install build
```

Installs the TUI as `torlinkc` and the console harness as
`torlinkc_core_cli` into `/usr/local/bin` (CMake's default
`CMAKE_INSTALL_PREFIX` on Linux), which is on `PATH` for most
distros -- so `torlinkc` works from anywhere afterward. For a user-local
install that needs no `sudo`, point it at a prefix already on your
`PATH` instead, e.g. `cmake --install build --prefix ~/.local`.

### Test

```sh
cd build && ctest --output-on-failure
# or directly, for more control:
./build/tests/torlinkc_tests
```

## Running

```sh
./build/apps/tui/torlinkc_tui
# or, if installed (see above):
torlinkc
```

Opens straight to a search screen. Type a query and press Enter to search
across all 10 sources at once; `Tab` moves between the sidebar and the
current pane; arrow keys (or `hjkl`) navigate. Press `?` for the full key
list. State (queue, history, seeds, config) lives under
`$XDG_DATA_HOME`/`$XDG_CONFIG_HOME` (or their usual fallbacks) under a
`torlinkc` directory — deliberately separate from the original Node app's
`torlink` directory, so the two can coexist on a dev machine without one
corrupting the other's state file. Set `TORLINK_STATE_DIR` to point both at
a different location instead (handy for testing in a sandbox).

## Project layout

```
include/torlinkc/   public headers, mirroring src/
src/
  engine/            download queue, libtorrent wrapper, persistence, bootguard
  sources/           the 10 search scrapers + registry + magnet/RSS helpers
  config/            config file, download-folder, tracker-list handling
  util/              net (HTTP + retry/cancel), date parsing, formatting, ...
  ui/                AppState, the engine/search background threads, and
                     all FTXUI-facing pure logic (theme, sort, filter, ...)
apps/
  tui/               the interactive terminal app (main.cpp)
  core_cli/          the headless console harness
phase0/              the two toolchain smoke tests
tests/               doctest suite, one file per module under test
```

Each phase's rationale and the architectural decisions behind it (why
libtorrent-rasterbar, the three-thread model behind the TUI, why certain
TypeScript modules port near-verbatim and others don't) are recorded in the
commit messages for that phase — `git log --oneline` is the fastest way to
see the shape of the project's growth so far.