torrent-tui 0.0.1 → 0.0.3

package/README.md

@@ -1,13 +1,17 @@
 # torrent-tui
 
-**A Bun-powered terminal BitTorrent client.** Add `.torrent` files, manage active downloads, and inspect transfer state from a focused TUI.
+**A terminal BitTorrent client for focused download management.** Add `.torrent` files, track active transfers, and manage sessions from a clean keyboard-driven interface.
 
 [![npm version](https://img.shields.io/npm/v/torrent-tui?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/torrent-tui)
-[![CI](https://img.shields.io/github/actions/workflow/status/ryadios/torrent-tui/ci.yml?branch=main&style=for-the-badge&logo=github)](https://github.com/ryadios/torrent-tui/actions/workflows/ci.yml)
+[![gzipped](https://img.shields.io/badge/gzipped-39%20KB-2563eb?style=for-the-badge)](https://www.npmjs.com/package/torrent-tui)
+[![npm unpacked size](https://img.shields.io/npm/unpacked-size/torrent-tui?style=for-the-badge)](https://www.npmjs.com/package/torrent-tui)
+[![CI](https://img.shields.io/github/actions/workflow/status/ryadios/torrent-tui/release.yml?branch=main&style=for-the-badge&logo=github)](https://github.com/ryadios/torrent-tui/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/torrent-tui?style=for-the-badge)](./LICENSE)
 
 [Install](#install) · [Quickstart](#quickstart) · [Commands](#commands) · [Configuration](#configuration) · [Development](#development)
 
+![torrent-tui terminal interface](./docs/screenshot.png)
+
 > [!NOTE]
 > `torrent-tui` currently requires [Bun](https://bun.sh). Standalone binaries are planned after the npm CLI release path is stable.
 
@@ -63,6 +67,7 @@ The package also exposes a few command-line checks around the same torrent engin
 ```bash
 torrent-tui --help
 torrent-tui --version
+torrent-tui file.torrent
 torrent-tui file.torrent --verify
 torrent-tui file.torrent --handshake
 torrent-tui file.torrent --download
@@ -71,7 +76,7 @@ torrent-tui file.torrent --download
 | Command | Description |
 | --- | --- |
 | `torrent-tui` | Start the terminal UI. |
-| `torrent-tui <file.torrent>` | Announce to trackers and print peers. |
+| `torrent-tui <file.torrent>` | Start the TUI and add the torrent. |
 | `torrent-tui <file.torrent> --verify` | Create storage and verify local pieces. |
 | `torrent-tui <file.torrent> --handshake` | Connect to peers and print a connection summary. |
 | `torrent-tui <file.torrent> --download` | Run the downloader without launching the TUI. |
@@ -100,6 +105,51 @@ Resume data is stored under:
 ${XDG_DATA_HOME:-~/.local/share}/torrent-tui/resume
 ```
 
+The session registry is stored at:
+
+```text
+${XDG_DATA_HOME:-~/.local/share}/torrent-tui/session.json
+```
+
+It keeps the list of torrents the TUI should restore on startup.
+
+### Torrent States
+
+The TUI shows detailed per-torrent states while keeping the sidebar filters simple.
+
+| State | Meaning |
+| --- | --- |
+| `Queued` | The `.torrent` was accepted and is waiting for engine startup. |
+| `Checking` | Local files are being checked against torrent piece hashes. |
+| `Connecting` | Trackers were contacted and the client is connecting to peers. |
+| `Downloading` | Pieces are actively being requested or received. |
+| `Stalled` | The torrent is incomplete but has no usable peers right now. Press `Space` to retry. |
+| `Paused` | The active downloader was paused by the user. |
+| `Seeding` | All pieces are present and the torrent can upload to peers. |
+| `Stopped` | The torrent is saved in the session but not running. |
+| `Error` | Startup, storage, or torrent metadata handling failed. |
+
+The `Downloading` sidebar filter includes queued, checking, connecting, downloading, and stalled torrents so active work stays grouped together.
+
+### What Each Setting Does
+
+| Setting | Purpose | When it applies |
+| --- | --- | --- |
+| `downloadPath` | Where torrent payload files are written and verified. | On torrent add, resume, verify, and startup restore. |
+| `torrentFolder` | Folder shown by the add-torrent dialog. | When you open the add dialog. |
+| `maxConnections` | Maximum number of peers the client will connect to per torrent. | During peer discovery and download. |
+
+### Tuning Tips
+
+- Use a fast local SSD for `downloadPath` if you want quicker verification and fewer stalls on reopen.
+- Point `torrentFolder` at the directory where you keep `.torrent` files so adding torrents is faster.
+- Lower `maxConnections` if your network or CPU struggles with many peers; raise it if you want more parallel peer selection.
+- Fresh torrents skip full zero-file verification. Existing files are checked cooperatively, so the TUI should stay responsive during large rechecks.
+- If a torrent stays `Stalled`, the client did not find a usable peer. Try again later with `Space`, or check tracker availability.
+- Settings are read when the app starts. If you edit `settings.json` manually, restart the app to pick up the changes.
+- If the settings file is invalid, torrent-tui falls back to defaults and logs a config warning.
+- `session.json` and the resume files are rewritten automatically as torrent state changes, so you normally do not need to edit them by hand.
+
 ## Status
 
 `0.0.1` is a basic release intended for early CLI usage.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "torrent-tui",
-	"version": "0.0.1",
+	"version": "0.0.3",
 	"description": "A Bun-powered terminal BitTorrent client.",
 	"module": "src/index.ts",
 	"type": "module",
@@ -20,9 +20,13 @@
 		"dev": "bun --watch src/index.ts",
 		"check": "bun src/index.ts --download",
 		"smoke": "bin/torrent-tui --help && bin/torrent-tui --version && if bin/torrent-tui nope.txt; then echo \"Expected invalid torrent path to fail\"; exit 1; fi",
+		"bench:startup": "bun scripts/benchmark-startup.ts",
+		"bench:verify": "bun scripts/benchmark-verify.ts",
+		"test": "bun test",
+		"test:watch": "bun test --watch",
 		"typecheck": "tsc --noEmit",
 		"check:fix": "biome check --write --unsafe",
-		"release:check": "bun run typecheck && bun publish --dry-run"
+		"release:check": "bun run typecheck && bun test && bun publish --dry-run"
 	},
 	"keywords": [
 		"bittorrent",

package/src/app.ts

@@ -34,7 +34,7 @@ export class App {
 	private layout!: LayoutDimensions;
 	private resizeTimeout: ReturnType<typeof setTimeout> | null = null;
 
-	async start(): Promise<void> {
+	async start(initialTorrentPath?: string): Promise<void> {
 		const config = loadConfig();
 
 		this.renderer = await createCliRenderer({ exitOnCtrlC: true });
@@ -62,6 +62,7 @@ export class App {
 			this.store,
 			this.sidebar,
 			this.contentWindow,
+			this.statusBar,
 			this.toastManager,
 		);
 		// Wire ConfirmDialog — callbacks are set inside the controller setter
@@ -101,41 +102,27 @@ export class App {
 			this.bridge.removeTorrent(id, deleteFiles);
 		};
 
-		this.addDialog.onSelect = async (filePath) => {
+		this.addDialog.onSelect = (filePath) => {
 			this.controller.focusMode = "global";
 			const filename = filePath.split("/").pop() ?? filePath;
-			this.toastManager.show({
-				id: `add-${Date.now()}`,
-				type: "info",
-				title: "Adding torrent",
-				message: filename,
-			});
+			this.renderer.requestRender();
 
-			try {
-				await this.bridge.addTorrent(filePath);
-				this.toastManager.show({
-					id: `added-${Date.now()}`,
-					type: "success",
-					title: "Download started",
-					message: filename,
-				});
-			} catch (err) {
-				this.toastManager.show({
-					id: `err-${Date.now()}`,
-					type: "error",
-					title: "Failed to add",
-					message: err instanceof Error ? err.message : String(err),
-				});
-			}
+			setTimeout(() => {
+				this.addTorrentInBackground(filePath, filename);
+			}, 0);
 		};
 
-		this.store.subscribe((state) => {
-			this.statusBar.update(state);
-		});
-
 		await this.bridge.restoreSession();
 		this.controller.start();
 
+		if (initialTorrentPath) {
+			const filename =
+				initialTorrentPath.split("/").pop() ?? initialTorrentPath;
+			setTimeout(() => {
+				this.addTorrentInBackground(initialTorrentPath, filename);
+			}, 0);
+		}
+
 		this.renderer.on("resize", (width: number, height: number) => {
 			this.handleResize(width, height);
 		});
@@ -154,4 +141,38 @@ export class App {
 			this.confirmDialog.updateLayout(this.layout);
 		}, 100);
 	}
+
+	private async addTorrentInBackground(
+		filePath: string,
+		filename: string,
+	): Promise<void> {
+		try {
+			const result = await this.bridge.addTorrent(filePath);
+			this.toastManager.show({
+				id: `added-${Date.now()}`,
+				type: result.added ? "success" : "info",
+				title: result.added ? "Torrent added" : "Torrent already added",
+				message: result.name || filename,
+			});
+			this.renderer.requestRender();
+
+			if (result.added) {
+				this.bridge.startTorrent(result.id).catch((err: unknown) => {
+					this.toastManager.show({
+						id: `start-err-${Date.now()}`,
+						type: "error",
+						title: "Failed to start",
+						message: err instanceof Error ? err.message : String(err),
+					});
+				});
+			}
+		} catch (err) {
+			this.toastManager.show({
+				id: `err-${Date.now()}`,
+				type: "error",
+				title: "Failed to add",
+				message: err instanceof Error ? err.message : String(err),
+			});
+		}
+	}
 }

package/src/config/index.ts

@@ -1,7 +1,9 @@
 // Config loader - reads from ~/.config/torrent-tui/settings.json
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { getConfigDir, getConfigPath } from "../utils/paths";
+import { existsSync, readFileSync } from "node:fs";
+import { log } from "../torrent/metadata";
+import { writeJsonAtomic } from "../utils/json";
+import { getConfigPath } from "../utils/paths";
 import { type AppSettings, DEFAULT_SETTINGS, settingsSchema } from "./settings";
 
 const SETTINGS_FILE = "settings.json";
@@ -24,18 +26,14 @@ export function loadConfig(): AppSettings {
 			return result.data;
 		}
 
+		log("config", "invalid settings file — using defaults");
 		return { ...DEFAULT_SETTINGS };
 	} catch {
+		log("config", "could not read settings file — using defaults");
 		return { ...DEFAULT_SETTINGS };
 	}
 }
 
 export function saveConfig(settings: AppSettings): void {
-	try {
-		mkdirSync(getConfigDir(), { recursive: true });
-		const configPath = getConfigPath(SETTINGS_FILE);
-		writeFileSync(configPath, JSON.stringify(settings, null, 2), "utf-8");
-	} catch {
-		// Silently fail
-	}
+	writeJsonAtomic(getConfigPath(SETTINGS_FILE), settings);
 }

package/src/constants/index.ts

@@ -1,5 +1,4 @@
 export const APP_NAME = "torrent-tui";
-export const VERSION = "0.0.1";
 
 export const SIDEBAR_WIDTH = 20;
 

package/src/controllers/app-controller.ts

@@ -1,24 +1,37 @@
 import type { CliRenderer, KeyEvent } from "@opentui/core";
 import { SIDEBAR_ITEMS } from "../constants";
 import type { ConfirmDialog } from "../layout/confirm-dialog";
-import type { ContentWindow } from "../layout/content-window";
+import type { ContentWindow, FocusArea } from "../layout/content-window";
+import {
+	type DetailTab,
+	getDetailMaxScrollOffset,
+} from "../layout/detail-panel";
 import type { Sidebar } from "../layout/sidebar";
+import type { StatusBar } from "../layout/status-bar";
 import type { ToastManager } from "../layout/toast-manager";
 import type { Store } from "../store";
 import { filterTorrents } from "../utils/filter";
 
 type FocusMode = "global" | "dialog";
-type FocusArea = "sidebar" | "table";
+const DETAIL_TABS: DetailTab[] = ["Pieces", "Peers", "Files"];
 
 export class AppController {
 	private renderer: CliRenderer;
 	private store: Store;
 	private sidebar: Sidebar;
 	private contentWindow: ContentWindow;
+	private statusBar: StatusBar;
 	private toastManager: ToastManager;
 	focusMode: FocusMode = "global";
 	focusArea: FocusArea = "sidebar";
 	private tableSelectedIndex = 0;
+	private detailTabIndex = 0;
+	private detailScrollOffsets: Record<DetailTab, number> = {
+		Pieces: 0,
+		Peers: 0,
+		Files: 0,
+	};
+	private lastDetailTorrentId: string | null = null;
 	private pendingDeleteId: string | null = null;
 
 	// Injected by App after bridge/dialog are created
@@ -26,18 +39,21 @@ export class AppController {
 	onQuit?: () => void;
 	onDialogClose?: () => void;
 	onDialogInput?: (key: string) => boolean;
-	onPauseTorrent?: (id: string) => void;
-	onResumeTorrent?: (id: string) => void;
-	onStartTorrent?: (id: string) => void;
-	onRemoveTorrent?: (id: string, deleteFiles: boolean) => void;
+	onPauseTorrent?: (id: string) => Promise<void> | void;
+	onResumeTorrent?: (id: string) => Promise<void> | void;
+	onStartTorrent?: (id: string) => Promise<void> | void;
+	onRemoveTorrent?: (id: string, deleteFiles: boolean) => Promise<void> | void;
 
 	private _confirmDialog: ConfirmDialog | null = null;
 	set confirmDialog(dialog: ConfirmDialog) {
 		this._confirmDialog = dialog;
 		dialog.onConfirm = () => {
 			this.focusMode = "global";
-			if (this.pendingDeleteId) {
-				this.onRemoveTorrent?.(this.pendingDeleteId, true);
+			const pendingDeleteId = this.pendingDeleteId;
+			if (pendingDeleteId) {
+				this.runTorrentAction("remove torrent", () =>
+					this.onRemoveTorrent?.(pendingDeleteId, true),
+				);
 				this.pendingDeleteId = null;
 			}
 		};
@@ -52,12 +68,14 @@ export class AppController {
 		store: Store,
 		sidebar: Sidebar,
 		contentWindow: ContentWindow,
+		statusBar: StatusBar,
 		toastManager: ToastManager,
 	) {
 		this.renderer = renderer;
 		this.store = store;
 		this.sidebar = sidebar;
 		this.contentWindow = contentWindow;
+		this.statusBar = statusBar;
 		this.toastManager = toastManager;
 	}
 
@@ -69,8 +87,15 @@ export class AppController {
 			} else if (len === 0) {
 				this.tableSelectedIndex = 0;
 			}
+			this.syncDetailState();
 			this.sidebar.update(state, this.focusArea);
-			this.contentWindow.update(this.focusArea, this.tableSelectedIndex);
+			this.contentWindow.update(
+				this.focusArea,
+				this.tableSelectedIndex,
+				this.getDetailTab(),
+				this.getDetailScrollOffset(),
+			);
+			this.statusBar.update(state, this.focusArea);
 		});
 
 		this.renderer.keyInput.on("keypress", (key) => {
@@ -83,12 +108,104 @@ export class AppController {
 	private refreshView(): void {
 		const state = this.store.getState();
 		this.sidebar.update(state, this.focusArea);
-		this.contentWindow.update(this.focusArea, this.tableSelectedIndex);
+		this.contentWindow.update(
+			this.focusArea,
+			this.tableSelectedIndex,
+			this.getDetailTab(),
+			this.getDetailScrollOffset(),
+		);
+		this.statusBar.update(state, this.focusArea);
+	}
+
+	private runTorrentAction(
+		label: string,
+		action: () => Promise<void> | void,
+	): void {
+		Promise.resolve()
+			.then(action)
+			.catch((err: unknown) => {
+				this.toastManager.show({
+					id: `action-${Date.now()}`,
+					type: "error",
+					title: `Failed to ${label}`,
+					message: err instanceof Error ? err.message : String(err),
+				});
+			});
 	}
 
 	private getSelectedId(): string | null {
 		const state = this.store.getState();
-		return filterTorrents(state.torrents, state.selectedView)[this.tableSelectedIndex]?.id ?? null;
+		return (
+			filterTorrents(state.torrents, state.selectedView)[
+				this.tableSelectedIndex
+			]?.id ?? null
+		);
+	}
+
+	private getDetailTab(): DetailTab {
+		return DETAIL_TABS[this.detailTabIndex] ?? "Pieces";
+	}
+
+	private moveDetailTab(delta: number): void {
+		this.detailTabIndex =
+			(this.detailTabIndex + delta + DETAIL_TABS.length) % DETAIL_TABS.length;
+		this.refreshView();
+	}
+
+	private getDetailScrollOffset(): number {
+		return this.detailScrollOffsets[this.getDetailTab()] ?? 0;
+	}
+
+	private setDetailScrollOffset(offset: number): void {
+		this.detailScrollOffsets[this.getDetailTab()] = offset;
+	}
+
+	private resetDetailScrollOffsets(): void {
+		this.detailScrollOffsets = {
+			Pieces: 0,
+			Peers: 0,
+			Files: 0,
+		};
+	}
+
+	private getSelectedTorrent() {
+		const state = this.store.getState();
+		return (
+			filterTorrents(state.torrents, state.selectedView)[
+				this.tableSelectedIndex
+			] ?? null
+		);
+	}
+
+	private syncDetailState(): void {
+		const torrentId = this.getSelectedTorrent()?.id ?? null;
+		if (torrentId !== this.lastDetailTorrentId) {
+			this.lastDetailTorrentId = torrentId;
+			this.resetDetailScrollOffsets();
+		}
+		const maxOffset = getDetailMaxScrollOffset(
+			this.getSelectedTorrent(),
+			this.getDetailTab(),
+			this.contentWindow.getDetailBodyRowCount(),
+		);
+		this.setDetailScrollOffset(
+			Math.max(0, Math.min(this.getDetailScrollOffset(), maxOffset)),
+		);
+	}
+
+	private moveDetailScroll(delta: number): void {
+		const maxOffset = getDetailMaxScrollOffset(
+			this.getSelectedTorrent(),
+			this.getDetailTab(),
+			this.contentWindow.getDetailBodyRowCount(),
+		);
+		const nextOffset = Math.max(
+			0,
+			Math.min(this.getDetailScrollOffset() + delta, maxOffset),
+		);
+		if (nextOffset === this.getDetailScrollOffset()) return;
+		this.setDetailScrollOffset(nextOffset);
+		this.refreshView();
 	}
 
 	private handleKeyPress(key: KeyEvent): void {
@@ -110,57 +227,113 @@ export class AppController {
 			return;
 		}
 
+		if (key.shift && key.name === "tab") {
+			this.focusArea = this.previousFocusArea();
+			this.refreshView();
+			return;
+		}
+
 		if (key.name === "tab") {
-			this.focusArea = this.focusArea === "sidebar" ? "table" : "sidebar";
+			this.focusArea = this.nextFocusArea();
 			this.refreshView();
 			return;
 		}
 
+		if (this.focusArea === "details") {
+			if (
+				key.name === "h" ||
+				key.name === "[" ||
+				key.name === "leftbracket" ||
+				key.name === "left"
+			) {
+				this.moveDetailTab(-1);
+				return;
+			}
+			if (
+				key.name === "l" ||
+				key.name === "]" ||
+				key.name === "rightbracket" ||
+				key.name === "right"
+			) {
+				this.moveDetailTab(1);
+				return;
+			}
+		}
+
 		if (key.name === "j" || key.name === "down") {
 			if (this.focusArea === "sidebar") {
 				const total = SIDEBAR_ITEMS.status.length;
 				const state = this.store.getState();
 				const next = (state.selectedIndex + 1) % total;
-				this.store.setState({ selectedIndex: next, selectedView: SIDEBAR_ITEMS.status[next] ?? "All" });
-			} else {
+				this.store.setState({
+					selectedIndex: next,
+					selectedView: SIDEBAR_ITEMS.status[next] ?? "All",
+				});
+			} else if (this.focusArea === "table") {
 				const state = this.store.getState();
 				const len = filterTorrents(state.torrents, state.selectedView).length;
 				if (len > 0) {
-					this.tableSelectedIndex = Math.min(this.tableSelectedIndex + 1, len - 1);
+					this.tableSelectedIndex = Math.min(
+						this.tableSelectedIndex + 1,
+						len - 1,
+					);
 					this.refreshView();
 				}
+			} else if (this.focusArea === "details") {
+				this.moveDetailScroll(1);
 			}
 		} else if (key.name === "k" || key.name === "up") {
 			if (this.focusArea === "sidebar") {
 				const total = SIDEBAR_ITEMS.status.length;
 				const state = this.store.getState();
 				const prev = (state.selectedIndex - 1 + total) % total;
-				this.store.setState({ selectedIndex: prev, selectedView: SIDEBAR_ITEMS.status[prev] ?? "All" });
-			} else {
+				this.store.setState({
+					selectedIndex: prev,
+					selectedView: SIDEBAR_ITEMS.status[prev] ?? "All",
+				});
+			} else if (this.focusArea === "table") {
 				if (this.tableSelectedIndex > 0) {
 					this.tableSelectedIndex--;
 					this.refreshView();
 				}
+			} else if (this.focusArea === "details") {
+				this.moveDetailScroll(-1);
 			}
 		} else if (key.name === "space") {
 			if (this.focusArea === "table") {
 				const id = this.getSelectedId();
 				if (!id) return;
 				const state = this.store.getState();
-				const torrent = filterTorrents(state.torrents, state.selectedView)[this.tableSelectedIndex];
+				const torrent = filterTorrents(state.torrents, state.selectedView)[
+					this.tableSelectedIndex
+				];
 				if (!torrent) return;
 				if (torrent.status === "downloading") {
-					this.onPauseTorrent?.(id);
+					this.runTorrentAction("pause torrent", () =>
+						this.onPauseTorrent?.(id),
+					);
 				} else if (torrent.status === "paused") {
-					this.onResumeTorrent?.(id);
-				} else if (torrent.status === "stopped") {
-					this.onStartTorrent?.(id);
+					this.runTorrentAction("resume torrent", () =>
+						this.onResumeTorrent?.(id),
+					);
+				} else if (
+					torrent.status === "stopped" ||
+					torrent.status === "stalled" ||
+					torrent.status === "error" ||
+					torrent.status === "missing"
+				) {
+					this.runTorrentAction("start torrent", () =>
+						this.onStartTorrent?.(id),
+					);
 				}
 			}
 		} else if (key.name === "d" && !key.shift) {
 			if (this.focusArea === "table") {
 				const id = this.getSelectedId();
-				if (id) this.onRemoveTorrent?.(id, false);
+				if (id)
+					this.runTorrentAction("remove torrent", () =>
+						this.onRemoveTorrent?.(id, false),
+					);
 			}
 		} else if (key.name === "d" && key.shift) {
 			if (this.focusArea === "table") {
@@ -177,4 +350,26 @@ export class AppController {
 			this.onQuit?.();
 		}
 	}
+
+	private nextFocusArea(): FocusArea {
+		switch (this.focusArea) {
+			case "sidebar":
+				return "table";
+			case "table":
+				return "details";
+			case "details":
+				return "sidebar";
+		}
+	}
+
+	private previousFocusArea(): FocusArea {
+		switch (this.focusArea) {
+			case "sidebar":
+				return "details";
+			case "table":
+				return "sidebar";
+			case "details":
+				return "table";
+		}
+	}
 }