commit beb451fa0d60e7c2d04f5b21e133a8f544a3e8e7
Author: MrJensK <jens.se@icloud.com>
AuthorDate: Sun Aug 23 11:46:54 2026 +0200
Commit: MrJensK <jens.se@icloud.com>
CommitDate: Sun Aug 23 11:46:54 2026 +0200
Add README: status, build instructions, project layout
---
README.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 114 insertions(+)
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0010278
--- /dev/null
+++ b/README.md
@@ -0,0 +1,114 @@
+# 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
+
+### Test
+
+```sh
+cd build && ctest --output-on-failure
+# or directly, for more control:
+./build/tests/torlinkc_tests
+```
+
+## Running
+
+```sh
+./build/apps/tui/torlinkc_tui
+```
+
+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.